maya.utils.converter.helpers
============================

.. py:module:: maya.utils.converter.helpers

.. autoapi-nested-parse::

   Blessed helper expansion registry.

   Blessed helpers are tik.maya methods that represent stable, well-understood
   semantic operations that can be safely expanded into known sequences of
   cmds (or OpenMaya) calls.

   Each helper expansion must:
   - Declare the tik.maya method name
   - Declare its cmds expansion
   - Be testable in isolation



Attributes
----------

.. autoapisummary::

   maya.utils.converter.helpers.UNSUPPORTED_METHODS


Classes
-------

.. autoapisummary::

   maya.utils.converter.helpers.HelperExpansion
   maya.utils.converter.helpers.HelperRegistry
   maya.utils.converter.helpers.UnsupportedMethod


Functions
---------

.. autoapisummary::

   maya.utils.converter.helpers.check_method_support
   maya.utils.converter.helpers.create_default_registry
   maya.utils.converter.helpers.get_default_registry
   maya.utils.converter.helpers.get_unsupported_reason


Module Contents
---------------

.. py:class:: HelperExpansion

   Definition of a blessed helper expansion.

   Attributes:
       method_name: The tik.maya method name (e.g., "unlock_normals").
       type_name: The tik.maya type this method belongs to (e.g., "Mesh").
       description: Human-readable description of what this helper does.
       cmds_template: Template or callable for generating cmds code.
       requires_openmaya: Whether the expansion uses OpenMaya calls.
       notes: Additional notes about the expansion.


   .. py:method:: expand(node_expr: str, args: List[str], kwargs: Dict[str, str]) -> str

      Expand this helper into cmds code.

      Args:
          node_expr: The expression for the node (e.g., "my_mesh").
          args: Positional arguments passed to the method.
          kwargs: Keyword arguments passed to the method.

      Returns:
          The expanded cmds code string.



   .. py:attribute:: cmds_template
      :type:  str


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: method_name
      :type:  str


   .. py:attribute:: notes
      :type:  Optional[str]
      :value: None



   .. py:attribute:: requires_openmaya
      :type:  bool
      :value: False



   .. py:attribute:: type_name
      :type:  str


.. py:class:: HelperRegistry

   Registry for blessed helper expansions.

   The registry maintains a collection of helper expansions that have been
   explicitly approved for automatic conversion. Only helpers registered
   here will be expanded; all others will be flagged as unsupported.


   .. py:method:: get(type_name: str, method_name: str) -> Optional[HelperExpansion]

      Get a helper expansion by type and method name.

      Args:
          type_name: The tik.maya type name.
          method_name: The method name.

      Returns:
          The HelperExpansion if registered, None otherwise.



   .. py:method:: is_blessed(type_name: str, method_name: str) -> bool

      Check if a method is a blessed helper.

      Args:
          type_name: The tik.maya type name.
          method_name: The method name.

      Returns:
          True if the method is registered as a blessed helper.



   .. py:method:: list_helpers() -> List[HelperExpansion]

      List all registered helpers.

      Returns:
          List of all registered HelperExpansion instances.



   .. py:method:: register(method_name: str, type_name: str, description: str, cmds_template: str, requires_openmaya: bool = False, notes: Optional[str] = None) -> HelperRegistry

      Register a new blessed helper expansion.

      Args:
          method_name: The tik.maya method name.
          type_name: The tik.maya type this method belongs to.
          description: Human-readable description.
          cmds_template: Template for generating cmds code.
          requires_openmaya: Whether OpenMaya is used.
          notes: Additional notes.

      Returns:
          Self for method chaining.



.. py:class:: UnsupportedMethod

   Represents an unsupported method that cannot be converted.


   .. py:attribute:: line_number
      :type:  int


   .. py:attribute:: method_name
      :type:  str


   .. py:attribute:: original_code
      :type:  str


   .. py:attribute:: reason
      :type:  str


   .. py:attribute:: type_name
      :type:  Optional[str]


.. py:function:: check_method_support(type_name: Optional[str], method_name: str, registry: Optional[HelperRegistry] = None) -> bool

   Check if a method call is supported for conversion.

   A method is supported if:
   1. It's handled by a built-in rule, OR
   2. It's registered as a blessed helper

   Args:
       type_name: The tik.maya type name (if known).
       method_name: The method name.
       registry: Helper registry to check (uses default if None).

   Returns:
       True if the method is supported for conversion.


.. py:function:: create_default_registry() -> HelperRegistry

   Create and populate the default helper registry.

   This contains the initial set of blessed helpers that are safe
   for automatic expansion.

   Returns:
       A populated HelperRegistry instance.


.. py:function:: get_default_registry() -> HelperRegistry

   Get the default helper registry (lazy initialization).

   Returns:
       The default HelperRegistry instance.


.. py:function:: get_unsupported_reason(method_name: str) -> Optional[str]

   Get the reason why a method is unsupported.

   Args:
       method_name: The method name.

   Returns:
       The reason string if known, None otherwise.


.. py:data:: UNSUPPORTED_METHODS
   :type:  Dict[str, str]