pytmc 2.18.2__tar.gz → 2.19.0__tar.gz

pytmc-2.19.0/.github/CODEOWNERS

@@ -0,0 +1,27 @@
+# default group
+* @pcdshub/python-reviewers @pcdshub/twincat-reviewers
+
+# language-specific group(s)
+## PYTHON files
+*.py @pcdshub/python-reviewers
+*.pyi @pcdshub/python-reviewers
+*.pyc @pcdshub/python-reviewers
+*.pyw @pcdshub/python-reviewers
+*.pyx @pcdshub/python-reviewers
+*.pyd @pcdshub/python-reviewers
+## TWINCAT files
+*.tsproj @pcdshub/twincat-reviewers
+*.plcproj @pcdshub/twincat-reviewers
+*.tmc @pcdshub/twincat-reviewers
+*.tpr @pcdshub/twincat-reviewers
+*.xti @pcdshub/twincat-reviewers
+*.TcTTO @pcdshub/twincat-reviewers
+*.TcPOU @pcdshub/twincat-reviewers
+*.TcDUT @pcdshub/twincat-reviewers
+*.TcGVL @pcdshub/twincat-reviewers
+*.TcVis @pcdshub/twincat-reviewers
+*.TcVMO @pcdshub/twincat-reviewers
+*.TcGTLO @pcdshub/twincat-reviewers
+
+# github folder holds administrative files
+.github/** @pcdshub/software-admin

{pytmc-2.18.2 → pytmc-2.19.0}/.gitmodules

@@ -16,3 +16,6 @@
 [submodule "pytmc/tests/projects/lcls-plc-lfe-motion"]
 	path = pytmc/tests/projects/lcls-plc-lfe-motion
 	url = https://github.com/pcdshub/lcls-plc-lfe-motion
+[submodule "pytmc/tests/projects/lcls-plc-motion-abstraction-sample"]
+	path = pytmc/tests/projects/lcls-plc-motion-abstraction-sample
+	url = https://github.com/pcdshub/lcls-plc-motion-abstraction-sample.git

{pytmc-2.18.2 → pytmc-2.19.0}/.pre-commit-config.yaml

@@ -9,7 +9,7 @@ exclude: |
 
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
     -   id: no-commit-to-branch
     -   id: trailing-whitespace
@@ -26,11 +26,11 @@ repos:
         exclude: '^(pytmc/bin/util.py)$'
 
 -   repo: https://github.com/pycqa/flake8.git
-    rev: 6.0.0
+    rev: 7.3.0
     hooks:
     -   id: flake8
 
 -   repo: https://github.com/timothycrosley/isort
-    rev: 5.12.0
+    rev: 7.0.0
     hooks:
     -   id: isort

{pytmc-2.18.2/pytmc.egg-info → pytmc-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pytmc
-Version: 2.18.2
+Version: 2.19.0
 Summary: Generate Epics DB records from TwinCAT .tmc files
 Author: SLAC National Accelerator Laboratory
 License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior
@@ -66,6 +66,7 @@ Requires-Dist: sphinx-argparse; extra == "doc"
 Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
 Requires-Dist: sphinx_rtd_theme>=1.2.0; extra == "doc"
 Requires-Dist: sphinxcontrib-websupport; extra == "doc"
+Dynamic: license-file
 
 PYTMC
 =====

{pytmc-2.18.2 → pytmc-2.19.0}/docs/source/release_notes.rst

@@ -2,6 +2,16 @@
  Release History
 =================
 
+v2.19.0 (2025-10-28)
+====================
+
+Changes
+-------
+- Add support for non-EtherCATMC type motors.
+  This is part of an PLC/IOC motion improvement project to improve the reliability
+  of our motion devices by avoiding custom motor record builds and related issues.
+
+
 v2.18.2 (2025-02-12)
 ====================
 

pytmc-2.19.0/pytmc/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.19.0'
+__version_tuple__ = version_tuple = (2, 19, 0)
+
+__commit_id__ = commit_id = 'g234728430'

{pytmc-2.18.2 → pytmc-2.19.0}/pytmc/bin/template.py

@@ -27,6 +27,8 @@ The following helpers are available in the environment::
     get_links
     get_linter_results
     get_motors
+    get_legacy_motors
+    get_stream_motors
     get_nc
     get_plc_by_name
     get_pou_call_blocks
@@ -57,7 +59,7 @@ import os
 import pathlib
 import sys
 from collections.abc import Generator
-from typing import Any, Optional, Union
+from typing import Any, List, Optional, Union
 
 import jinja2
 
@@ -312,15 +314,101 @@ def get_symbols_by_type(plc: parser.Plc) -> dict[str, list[parser.Symbol]]:
     return parser.separate_by_classname(symbols)
 
 
+def has_axis_link(stage: parser.Symbol_FB_MotionStage) -> bool:
+    """
+    Only valid for Symbol_FB_MotionStage (or alias); checks for axis-link pragma.
+    Returns True if an 'axis-link:' pragma is found, else False.
+    """
+    # Accept both direct class and known aliases for compatibility:
+    if not (isinstance(stage, parser.Symbol_FB_MotionStage) or
+            set(getattr(stage, "symbol_aliases", [])) & {'Symbol_FB_MotionStageNC', 'Symbol_FB_MotionStageNCDS402', 'Symbol_FB_MotionStageMCS2'}):
+        return False  # Not a supported FB_MotionStage type; skip
+
+    for pragma in parser.get_pragma(stage, name="pytmc"):
+        for line in pragma.splitlines():
+            if line.strip().startswith("axis-link:"):
+                return True
+    return False
+
+
+@functools.lru_cache
+def get_legacy_motors(plc: parser.Plc) -> list[parser.Symbol_ST_MotionStage]:
+    """
+    Find all valid legacy motors (ST_MotionStage) in the provided PLC.
+
+    Criteria:
+        - The symbol is of type Symbol_ST_MotionStage.
+        - The symbol is not a pointer (i.e., is_pointer is False).
+        - The symbol has a pytmc pragma (parser.has_pragma is True).
+
+    For each returned motor, a dynamic attribute 'is_legacy_motor' is set to True,
+    enabling template logic or further processing to easily distinguish legacy motors.
+
+    Args:
+        plc (parser.Plc): The parsed PLC object to examine.
+
+    Returns:
+        list[parser.Symbol_ST_MotionStage]:
+            List of all valid legacy motor symbols from this PLC.
+    """
+    symbols = get_symbols_by_type(plc)
+    st_motors = symbols.get("Symbol_ST_MotionStage", [])
+    legacy = []
+    for stage in st_motors:
+        if (
+            not stage.is_pointer
+            and parser.has_pragma(stage)
+        ):
+            stage.is_legacy_motor = True
+            legacy.append(stage)
+    return legacy
+
+
 @functools.lru_cache
-def get_motors(plc: parser.Plc) -> list[parser.Symbol_ST_MotionStage]:
-    """Get pragma'd motor symbols for the PLC (non-pointer ST_MotionStage)."""
+def get_stream_motors(plc: parser.Plc) -> list[parser.Symbol_FB_MotionStage]:
+    """
+    Find all valid stream (FB_MotionStage) motors in the given PLC.
+
+    Criteria for inclusion:
+        - The symbol is of type Symbol_FB_MotionStage.
+        - The symbol is not a pointer (i.e., 'is_pointer' is False).
+        - The symbol has a pytmc pragma (parser.has_pragma is True).
+        - The symbol has a valid axis-link pragma (checked with has_axis_link(stage)),
+          ensuring it maps to a real NC axis and is suitable for EPICS motor creation.
+
+    For each returned motor symbol, a dynamic attribute 'is_legacy_motor' is set to False,
+    distinguishing them from legacy motors during template generation or further logic.
+
+    Args:
+        plc (parser.Plc):
+            The parsed TwinCAT PLC object to search for motors.
+
+    Returns:
+        list[parser.Symbol_FB_MotionStage]:
+            A list of all valid stream (modern/FB_MotionStage) motor symbols
+            in this PLC, ready for StreamDevice-style and per-axis record creation.
+    """
     symbols = get_symbols_by_type(plc)
-    return [
-        stage
-        for stage in symbols.get("Symbol_ST_MotionStage", [])
-        if not stage.is_pointer and pragmas.has_pragma(stage)
-    ]
+    fb_motors = symbols.get("Symbol_FB_MotionStage", [])
+    stream = []
+    for stage in fb_motors:
+        if (
+            not stage.is_pointer
+            and parser.has_pragma(stage)
+            and has_axis_link(stage)
+        ):
+            stage.is_legacy_motor = False
+            stream.append(stage)
+    return stream
+
+
+@functools.lru_cache
+def get_motors(plc: parser.Plc) -> List[Union[parser.Symbol_ST_MotionStage, parser.Symbol_FB_MotionStage]]:
+    """
+    Return all valid motors for the PLC by concatenating legacy and stream (FB) motors.
+    Each entry is tagged via is_legacy_motor.
+    """
+    return get_legacy_motors(plc) + get_stream_motors(plc)
 
 
 def get_plc_by_name(
@@ -670,6 +758,8 @@ helpers = [
     get_links,
     get_linter_results,
     get_motors,
+    get_legacy_motors,
+    get_stream_motors,
     get_nc,
     get_plc_by_name,
     get_symbols,
@@ -762,6 +852,43 @@ def split_input_output(arg: str) -> tuple[str, str]:
     )
 
 
+def resolve_motors(template_args: dict) -> dict[str, Any]:
+    """
+    Given template_args (with macros and 'projects'), resolve the correct motors lists
+    for legacy and FB_MotionStage, enforcing that only one family is present.
+    Returns a context dict for updating template_args.
+    """
+    plc_name = template_args.get("plc", None)
+    projects_dict = template_args["projects"]
+
+    if plc_name is not None:
+        project, plc = get_plc_by_name(projects_dict, plc_name)
+        if plc is None:
+            raise RuntimeError(f"PLC '{plc_name}' not found in loaded projects!")
+    else:
+        # Default: take first PLC from the first project found (safe for single-PLC projects)
+        project = next(iter(projects_dict.values()))
+        plcs = list(project.plcs)
+        plc = plcs[0]
+
+    legacy_motors = get_legacy_motors(plc)
+    stream_motors = get_stream_motors(plc)
+
+    if legacy_motors and stream_motors:
+        raise RuntimeError(
+            f"Both legacy (ST_MotionStage) motors and stream (FB_MotionStage) motors are present. "
+            f"Not allowed! Legacy: {[m.name for m in legacy_motors]}, Stream: {[m.name for m in stream_motors]}"
+        )
+
+    motors = legacy_motors if legacy_motors else stream_motors
+
+    return {
+        "legacy_motors": legacy_motors,
+        "stream_motors": stream_motors,
+        "motors": motors,
+    }
+
+
 def main(
     projects: list[parser.AnyPath],
     templates: Optional[Union[list[str], str]] = None,
@@ -769,23 +896,17 @@ def main(
     debug: bool = False,
 ) -> dict[str, str]:
     """
-    Render template(s) based on a TwinCAT3 project, or XML-format file such as
-    TMC.
+    Render template(s) based on a TwinCAT3 project, or XML-format file such as TMC.
 
-    Parameters
-    ----------
-    projects : list
-        List of projects or TwinCAT project files (.sln, .tsproj, .tmc, etc.)
-
-    templates : str or list of str, optional
-        Template filename (default: standard input) to output filename
-        in the form ``input_filename[{os.pathsep}output_filename]``
-        Defaults to '-' (standard input -> standard output)
+    Args:
+        projects: List of project paths (.sln, .tsproj, .tmc, ...)
+        templates: Input template(s) (default: stdin; can be list or single string with [:] for output)
+        macros: Dict or list of "MACRO=VALUE" items, e.g., "plc=MyPLC"
+        debug: Interactive Python debug after render
 
-    debug : bool, optional
-        Open a debug session after rendering with IPython.
+    Returns:
+        all_rendered: Dict mapping input template to rendered output (string)
     """
-
     macros = macros or {}
     if not isinstance(macros, dict):
         macros = dict(_split_macro(macro) for macro in macros)
@@ -797,20 +918,17 @@ def main(
         templates = [templates]
 
     all_rendered = {}
+
     for template in templates:
         input_filename, output_filename = split_input_output(template)
         if input_filename == "-":
-            # Check if it's an interactive user to warn them what we're doing:
             is_tty = os.isatty(sys.stdin.fileno())
             if is_tty:
                 logger.warning("Reading template from standard input...")
                 logger.warning("Press ^D on a blank line when done.")
-
             template_text = sys.stdin.read()
             if is_tty:
-                logger.warning(
-                    "Read template from standard input (len=%d)", len(template_text)
-                )
+                logger.warning("Read template from standard input (len=%d)", len(template_text))
         else:
             with open(input_filename) as fp:
                 template_text = fp.read()
@@ -820,6 +938,10 @@ def main(
             template_args = get_render_context()
             template_args.update(projects_to_dict(*projects))
             template_args.update(**macros)
+
+            # updating template_args with motors
+            template_args.update(resolve_motors(template_args))
+
             rendered = render_template(template_text, template_args)
         except Exception as ex:
             stashed_exception = ex
@@ -828,7 +950,6 @@ def main(
         if not debug:
             if stashed_exception is not None:
                 raise stashed_exception
-
             if output_filename:
                 with open(output_filename, "w") as fp:
                     print(rendered, file=fp)
@@ -837,10 +958,7 @@ def main(
         else:
             message = ["Variables: projects, template_text, rendered, template_args. "]
             if stashed_exception is not None:
-                message.append(
-                    f"Exception: {type(stashed_exception)} " f"{stashed_exception}"
-                )
-
+                message.append(f"Exception: {type(stashed_exception)} {stashed_exception}")
             util.python_debug_session(namespace=locals(), message="\n".join(message))
         all_rendered[input_filename] = rendered
 

{pytmc-2.18.2 → pytmc-2.19.0}/pytmc/parser.py

@@ -1661,6 +1661,151 @@ class Symbol_ST_MotionStage(Symbol):
 Symbol_DUT_MotionStage = Symbol_ST_MotionStage
 
 
+def has_pragma(item, *, name: str = "pytmc"):
+    "Does `item` have a pragma titled `name`?"
+
+    return any(True for pragma in get_pragma(item, name=name) if pragma is not None)
+
+
+def get_pragma(
+    item: Union[SubItem, type[Symbol]], *, name: str = "pytmc"
+) -> Generator[str, None, None]:
+    """
+    Get all pragmas with a certain tag.
+
+    Parameters
+    ----------
+    item : parser.SubItem, parser.Symbol, parser.Symbol subclass
+        Representation of beckhoff variable or data structure
+
+    name : str, optional
+        Accept tmc entries where the <Name> field equals the passed string
+
+    Yields
+    ------
+    str
+
+    """
+    name_list = [name, f"plcAttribute_{name}"]
+    if hasattr(item, "Properties"):
+        properties = item.Properties[0]
+        for prop in getattr(properties, "Property", []):
+            # Return true if any of the names searched for are found
+            if any(indiv_name == prop.name for indiv_name in name_list):
+                yield prop.value
+
+
+class Symbol_FB_MotionStage(Symbol):
+    """[TMC] Customized Symbol representing only FB_MotionStage.
+
+    Variants:
+    - Symbol_FB_MotionStageNC
+    - Symbol_FB_MotionStageNCDS402
+    - Symbol_FB_MotionStageMCS2
+    """
+    symbol_aliases = ['Symbol_FB_MotionStageNC', 'Symbol_FB_MotionStageMCS2', 'Symbol_FB_MotionStageNCDS402']
+
+    def _repr_info(self):
+        repr_info = super()._repr_info()
+        try:
+            repr_info["nc_axis"] = self.nc_axis.name
+        except Exception as ex:
+            repr_info["nc_axis"] = repr(ex)
+        return repr_info
+
+    def get_axis_link(self):
+        """
+        Returns the first axis-link value from a pytmc pragma (e.g. 'GVL_Axes.Axes[2]').
+        If no pytmc pragma is found, returns None (treat symbol as ignored/simulation-only).
+        Raises RuntimeError if pragma is present but axis-link is missing or blank.
+        """
+        has_any_pytmc = False
+        for pragma_entry in get_pragma(self, name='pytmc'):
+            has_any_pytmc = True
+            for line in pragma_entry.splitlines():
+                line = line.strip()
+                if line.lower().startswith("axis-link:"):
+                    value = line.partition(":")[2].strip()
+                    if value:
+                        return value
+        if not has_any_pytmc:
+            # No pytmc pragma at all: not an EPICS-exported axis, just skip/return None
+            return None
+        # Had a pytmc pragma but no axis-link: this is a config error
+        raise RuntimeError(f"No valid axis-link pragma found for symbol '{self.name}'")
+
+    @property
+    def ncAxis(self):
+        """Returns the axis link value, e.g. 'gvl_axes.axes[2]'."""
+        # Note: GVL_Axes.Axes[n] in PLC is usually gvl_axes.axes[n] in NC
+        return self.get_axis_link().lower()
+
+    @property
+    def program_name(self):
+        """'Main' from 'Main.M1'"""
+        return self.name.split(".")[0]
+
+    @property
+    def motor_name(self):
+        """'M1' from 'Main.M1'"""
+        return self.name.split(".")[1]
+
+    @property
+    def nc_to_plc_link(self):
+        """
+        Returns the Link whose 'a[1]' contains the axis-link (and '.NcToPlc').
+        Raises RuntimeError for mismatches or missing self.plc.
+        """
+        plc = getattr(self, "plc", None)
+        if plc is None:
+            raise RuntimeError(f"Symbol {self.name!r} has no associated PLC (plc attribute is None)")
+        axis_link = self.get_axis_link()  # e.g. 'GVL_Axes.Axes[2]'
+        axis_link_lc = axis_link.lower()
+        for link in getattr(plc, "links", []):
+            a1_lc = link.a[1].lower()
+            # Look for axis-link pattern and NcToPlc ending
+            if axis_link_lc in a1_lc and a1_lc.endswith(".nctoplc"):
+                return link
+        # If not found, raise error with details
+        raise RuntimeError(
+            f"No NC-to-PLC link found for axis-link '{axis_link}' ({self.name!r})"
+        )
+
+    @property
+    def nc_axis(self):
+        """
+        The NC Axis object associated with this FB_MotionStage.
+        """
+        link = self.nc_to_plc_link
+        if link is None:
+            raise RuntimeError(f"No NC-to-PLC link found for {self.name}")
+
+        parent_name = link.parent.name.split("^")
+        if parent_name[0] == "TINC":
+            parent_name = parent_name[1:]
+
+        if len(parent_name) != 3:
+            raise RuntimeError(f"Unexpected link parent name format: {link.parent.name}")
+
+        task_name, axis_section, axis_name = parent_name
+
+        # Find correct NC from root
+        ncs = [
+            nc for nc in self.root.find(NC, recurse=False)
+            if hasattr(nc, 'SafTask') and nc.SafTask[0].name == task_name
+        ]
+        if not ncs:
+            raise RuntimeError(f"No NC with SafTask name {task_name!r} found.")
+
+        nc = ncs[0]
+        try:
+            nc_axis = nc.axis_by_name[axis_name]
+        except KeyError:
+            raise RuntimeError(f"No NC axis named {axis_name!r} found in NC {task_name!r}.")
+
+        return nc_axis
+
+
 class GVL(_TwincatProjectSubItem):
     "[TcGVL] A Global Variable List"
     Declaration: list

{pytmc-2.18.2 → pytmc-2.19.0}/pytmc/pragmas.py

@@ -7,12 +7,14 @@ import itertools
 import logging
 import math
 import re
-from collections.abc import Generator
-from typing import Union
 
 from . import parser
 from .record import RecordPackage
 
+# from collections.abc import Generator
+# from typing import Union
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -308,7 +310,7 @@ def _expand_configurations_from_chain(
     for item in chain:
         subitems = subitems.get(item.name, {})
         pragmas = list(
-            pragma for pragma in get_pragma(item, name=pragma) if pragma is not None
+            pragma for pragma in parser.get_pragma(item, name=pragma) if pragma is not None
         )
         if not pragmas:
             if allow_no_pragma:
@@ -712,45 +714,11 @@ class SingularChain:
 def find_pytmc_symbols(tmc, allow_no_pragma=False):
     "Find all symbols in a tmc file that contain pragmas"
     for symbol in tmc.find(parser.Symbol):
-        if has_pragma(symbol) or allow_no_pragma:
+        if parser.has_pragma(symbol) or allow_no_pragma:
             if symbol.name.count(".") == 1:
                 yield symbol
 
 
-def get_pragma(
-    item: Union[parser.SubItem, type[parser.Symbol]], *, name: str = "pytmc"
-) -> Generator[str, None, None]:
-    """
-    Get all pragmas with a certain tag.
-
-    Parameters
-    ----------
-    item : parser.SubItem, parser.Symbol, parser.Symbol subclass
-        Representation of beckhoff variable or data structure
-
-    name : str, optional
-        Accept tmc entries where the <Name> field equals the passed string
-
-    Yields
-    ------
-    str
-
-    """
-    name_list = [name, f"plcAttribute_{name}"]
-    if hasattr(item, "Properties"):
-        properties = item.Properties[0]
-        for prop in getattr(properties, "Property", []):
-            # Return true if any of the names searched for are found
-            if any(indiv_name == prop.name for indiv_name in name_list):
-                yield prop.value
-
-
-def has_pragma(item, *, name: str = "pytmc"):
-    "Does `item` have a pragma titled `name`?"
-
-    return any(True for pragma in get_pragma(item, name=name) if pragma is not None)
-
-
 def always_true(*a, **kwargs):
     return True
 
@@ -760,7 +728,7 @@ def chains_from_symbol(symbol, *, pragma: str = "pytmc", allow_no_pragma=False):
     if allow_no_pragma:
         condition = always_true
     else:
-        condition = has_pragma
+        condition = parser.has_pragma
     for full_chain in symbol.walk(condition=condition):
         configs = itertools.product(
             *_expand_configurations_from_chain(

{pytmc-2.18.2 → pytmc-2.19.0}/pytmc/tests/test_motion.py

@@ -2,7 +2,6 @@ from pathlib import Path
 
 from pytmc import parser
 from pytmc.bin import stcmd
-from pytmc.pragmas import get_pragma
 
 from .conftest import get_real_motor_symbols
 
@@ -98,7 +97,7 @@ def test_macro_in_motor_stcmd():
     tmc_item = parser.parse(file)
     all_motors = list(tmc_item.find(parser.Symbol_ST_MotionStage))
     yes_sub = [
-        motor for motor in all_motors if "@" in next(get_pragma(motor))
+        motor for motor in all_motors if "@" in next(parser.get_pragma(motor))
     ]
     assert len(yes_sub) > 0, "No motors found that need subs"
     assert len(all_motors) > len(yes_sub), "No motors found that don't need subs"
@@ -110,7 +109,7 @@ def test_macro_in_motor_stcmd():
             assert "$(PREFIX)" in prefix
         else:
             # Make sure the non-subs don't get distorted
-            assert prefix + name in next(get_pragma(motor))
+            assert prefix + name in next(parser.get_pragma(motor))
             # Make sure we didn't miscategorize a yes_sub
             assert "$(PREFIX)" not in prefix + name
         assert "@" not in prefix