The ``introspection.py`` module
===============================

.. py:module:: ansys.mechanical.mcp.introspection


Summary
-------








.. py:currentmodule:: introspection
.. tab-set::







    .. tab-item:: Functions

        .. list-table::
          :header-rows: 0
          :widths: auto


          * - :py:obj:`~find_objects_script`
            - Return the Mechanical script that searches the Outline tree.


          * - :py:obj:`~describe_object_script`
            - Return the Mechanical script that describes one object.


          * - :py:obj:`~search_api_script`
            - Return the Mechanical script that searches the API of the connected release.


          * - :py:obj:`~preview_change_script`
            - Return the Mechanical script that validates a property change without applying it.


          * - :py:obj:`~apply_change_script`
            - Return the Mechanical script that applies a previewed property change.


          * - :py:obj:`~check_script_script`
            - Return the Mechanical script that compiles a script and resolves its API names.


          * - :py:obj:`~close_matches`
            - Return the candidates closest to ``word``, preferring a case-insensitive match.


          * - :py:obj:`~extract_api_chains`
            - Collect attribute chains rooted in names the script does not define itself.


          * - :py:obj:`~store_preview`
            - Record a valid preview and return its single-use token.


          * - :py:obj:`~take_preview`
            - Consume a preview token, checking that it matches this session and change.




    .. tab-item:: Constants

        .. list-table::
          :header-rows: 0
          :widths: auto


          * - :py:obj:`~PREVIEW_TTL_SECONDS`
            - 


          * - :py:obj:`~MAX_PENDING_PREVIEWS`
            - 


          * - :py:obj:`~MAX_CHECKED_CHAINS`
            - 















Description
-----------

Object discovery, property change previews, and script checks.

The Mechanical-side scripts here inspect the connected session itself, so the
results always match the connected release instead of a bundled API snapshot.
They run in the Mechanical scripting engine, which is IronPython 2.7 for remote
sessions, so they avoid f-strings and annotations. Tool arguments reach them as
a base64-encoded JSON payload, which cannot break out of the script text.

..
    !! processed by numpydoc !!






Module detail
-------------

.. py:function:: find_objects_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that searches the Outline tree.
















   ..
       !! processed by numpydoc !!

.. py:function:: describe_object_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that describes one object.
















   ..
       !! processed by numpydoc !!

.. py:function:: search_api_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that searches the API of the connected release.
















   ..
       !! processed by numpydoc !!

.. py:function:: preview_change_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that validates a property change without applying it.
















   ..
       !! processed by numpydoc !!

.. py:function:: apply_change_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that applies a previewed property change.
















   ..
       !! processed by numpydoc !!

.. py:function:: check_script_script(args: dict[str, Any]) -> str

   
   Return the Mechanical script that compiles a script and resolves its API names.
















   ..
       !! processed by numpydoc !!

.. py:function:: close_matches(word: str, candidates: list[str], limit: int = 3) -> list[str]

   
   Return the candidates closest to ``word``, preferring a case-insensitive match.
















   ..
       !! processed by numpydoc !!

.. py:function:: extract_api_chains(script: str) -> tuple[list[dict[str, Any]], dict[str, Any] | None, bool]

   
   Collect attribute chains rooted in names the script does not define itself.


   :Parameters:

       **script** : :class:`python:str`
           Script source.



   :Returns:

       :class:`python:tuple`
           ``(chains, syntax_error, has_star_import)``. Each chain holds ``parts``
           (for example ``["Model", "Mesh", "ElementSize"]``), ``line``, and
           ``column``. ``syntax_error`` is set when the script is not valid Python 3,
           in which case no chains are returned.











   ..
       !! processed by numpydoc !!

.. py:function:: store_preview(store: dict[str, dict[str, Any]], mechanical: Any, object_id: int, property_name: str, value: Any, fingerprint: str) -> str

   
   Record a valid preview and return its single-use token.
















   ..
       !! processed by numpydoc !!

.. py:function:: take_preview(store: dict[str, dict[str, Any]], token: str, mechanical: Any, object_id: int, property_name: str, value: Any) -> dict[str, Any]

   
   Consume a preview token, checking that it matches this session and change.









   :Raises:

       :obj:`StalePreviewError`
           If the token is unknown, already used, expired, or from another session.

       :obj:`InvalidArgumentsError`
           If the token was issued for a different object, property, or value.







   ..
       !! processed by numpydoc !!

.. py:data:: PREVIEW_TTL_SECONDS
   :value: 600


.. py:data:: MAX_PENDING_PREVIEWS
   :value: 100


.. py:data:: MAX_CHECKED_CHAINS
   :value: 300