ml_switcheroo.plugins.utils
===========================

.. py:module:: ml_switcheroo.plugins.utils

.. autoapi-nested-parse::

   Shared Utilities for Plugins.

   This module provides common helper functions for AST manipulation and
   framework detection, decoupling individual plugins from hardcoded lists of libraries.
   It relies on the `HookContext` to dynamically resolve framework identities.



Functions
---------

.. autoapisummary::

   ml_switcheroo.plugins.utils.create_dotted_name
   ml_switcheroo.plugins.utils.is_framework_module_node


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

.. py:function:: create_dotted_name(name_str: str) -> libcst.BaseExpression

   Creates a CST Attribute chain from a dotted string.

   Example: "jax.numpy.add" -> Attribute(value=Attribute(value=Name("jax"), ...), ...)

   :param name_str: The dot-separated API path.
   :type name_str: str

   :returns: The constructed AST node.
   :rtype: cst.BaseExpression


.. py:function:: is_framework_module_node(node: libcst.CSTNode, ctx: ml_switcheroo.core.hooks.HookContext) -> bool

   Determines if a CST node represents a known framework namespace root.

   This is used to distinguish function calls (e.g. `torch.add(x)`) from method calls
   (e.g. `x.add()`). If the receiver `x` is a variable, this returns False.
   If the receiver is `torch`, it returns True.

   Logic:
       1. Checks the configured Source and Target frameworks in `ctx`.
       2. Checks the Global Semantics Registry (loaded adapters) via `ctx.semantics`.

   Decoupling Note:
       This logic no longer checks for hardcoded strings like "torch" or "jax".
       It relies entirely on the configuration passed in `ctx`.

   :param node: The node to inspect (e.g. the value of an Attribute).
   :type node: cst.CSTNode
   :param ctx: The execution context containing framework configuration.
   :type ctx: HookContext

   :returns: True if the node is a known framework identifier.
   :rtype: bool