pyrig 2.2.6__py3-none-any.whl

pyrig/src/modules/class_.py

@@ -0,0 +1,369 @@
+"""Class introspection and subclass discovery utilities.
+
+This module provides utilities for inspecting Python classes, extracting their
+methods, and discovering subclasses across packages. The subclass discovery
+system is central to pyrig's plugin architecture, enabling automatic discovery
+of ConfigFile implementations, Builder subclasses, and other extensible
+components.
+
+Key features:
+    - Method extraction with optional parent class filtering
+    - Class discovery within modules
+    - Recursive subclass discovery with package loading
+    - Intelligent "leaf class" filtering via `discard_parents`
+
+The `discard_parents` feature is particularly important: when multiple packages
+define subclasses in a chain (e.g., BaseConfig -> PyrigConfig -> UserConfig),
+only the most specific (leaf) classes are kept. This enables clean override
+behavior where user customizations replace base implementations.
+
+Example:
+    >>> from pyrig.src.modules.class_ import get_all_nonabstract_subclasses
+    >>> subclasses = get_all_nonabstract_subclasses(
+    ...     ConfigFile,
+    ...     load_package_before=my_package.dev.configs,
+    ...     discard_parents=True
+    ... )
+"""
+
+import inspect
+from collections.abc import Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any, overload
+
+from pyrig.src.modules.function import is_func
+from pyrig.src.modules.inspection import get_def_line, get_obj_members
+
+
+def get_all_methods_from_cls(
+    class_: type,
+    *,
+    exclude_parent_methods: bool = False,
+    include_annotate: bool = False,
+) -> list[Callable[..., Any]]:
+    """Extract all methods from a class.
+
+    Retrieves all method-like attributes from a class, including instance
+    methods, static methods, class methods, and properties. Methods are
+    returned sorted by their definition order in the source code.
+
+    This is used by pyrig to generate test skeletons for each method
+    in a class.
+
+    Args:
+        class_: The class to extract methods from.
+        exclude_parent_methods: If True, only includes methods defined directly
+            in this class, excluding inherited methods. Useful when generating
+            tests only for new methods in a subclass.
+        include_annotate: If False (default), excludes `__annotate__` methods
+            introduced in Python 3.14.
+
+    Returns:
+        A list of callable method objects, sorted by their line number
+        in the source file.
+
+    Example:
+        >>> class MyClass:
+        ...     def method_a(self): pass
+        ...     def method_b(self): pass
+        >>> methods = get_all_methods_from_cls(MyClass)
+        >>> [m.__name__ for m in methods]
+        ['method_a', 'method_b']
+    """
+    from pyrig.src.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_module_of_obj,
+    )
+
+    methods = [
+        (method, name)
+        for name, method in get_obj_members(class_, include_annotate=include_annotate)
+        if is_func(method)
+    ]
+
+    if exclude_parent_methods:
+        methods = [
+            (method, name)
+            for method, name in methods
+            if get_module_of_obj(method).__name__ == class_.__module__
+            and name in class_.__dict__
+        ]
+
+    only_methods = [method for method, _name in methods]
+    # sort by definition order
+    return sorted(only_methods, key=get_def_line)
+
+
+def get_all_cls_from_module(module: ModuleType | str) -> list[type]:
+    """Extract all classes defined directly in a module.
+
+    Retrieves all class objects that are defined in the specified module,
+    excluding classes imported from other modules. Classes are returned
+    sorted by their definition order.
+
+    This is used by pyrig to discover classes for test skeleton generation.
+
+    Args:
+        module: The module to extract classes from. Can be a module object
+            or a fully qualified module name string.
+
+    Returns:
+        A list of class types defined in the module, sorted by their
+        definition order in the source file.
+
+    Note:
+        Handles edge cases like Rust-backed classes (e.g., cryptography's
+        AESGCM) that may not have standard `__module__` attributes.
+
+    Example:
+        >>> import my_module
+        >>> classes = get_all_cls_from_module(my_module)
+        >>> [c.__name__ for c in classes]
+        ['ClassA', 'ClassB']
+    """
+    from pyrig.src.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_module_of_obj,
+    )
+
+    if isinstance(module, str):
+        module = import_module(module)
+
+    # necessary for bindings packages like AESGCM from cryptography._rust backend
+    default = ModuleType("default")
+    classes = [
+        obj
+        for _, obj in inspect.getmembers(module, inspect.isclass)
+        if get_module_of_obj(obj, default).__name__ == module.__name__
+    ]
+    # sort by definition order
+    return sorted(classes, key=get_def_line)
+
+
+def get_all_subclasses[T: type](
+    cls: T,
+    load_package_before: ModuleType | None = None,
+    *,
+    discard_parents: bool = False,
+) -> set[T]:
+    """Recursively discover all subclasses of a class.
+
+    Finds all direct and indirect subclasses of the given class. Because
+    Python's `__subclasses__()` only returns classes that have been imported,
+    you can optionally specify a package to walk (import) before discovery.
+
+    Args:
+        cls: The base class to find subclasses of.
+        load_package_before: Optional package to walk before discovery. All
+            modules in this package will be imported, ensuring any subclasses
+            defined there are registered with Python's subclass tracking.
+            When provided, results are filtered to only include classes from
+            this package.
+        discard_parents: If True, removes parent classes from the result when
+            both a parent and its child are present. This keeps only the most
+            specific (leaf) classes, enabling clean override behavior.
+
+    Returns:
+        A set of all subclasses (including the original class itself when
+        `load_package_before` is not specified).
+
+    Example:
+        >>> class Base: pass
+        >>> class Child(Base): pass
+        >>> class GrandChild(Child): pass
+        >>> get_all_subclasses(Base)
+        {Base, Child, GrandChild}
+        >>> get_all_subclasses(Base, discard_parents=True)
+        {GrandChild}
+    """
+    from pyrig.src.modules.package import (  # noqa: PLC0415  # avoid circular import
+        walk_package,
+    )
+
+    if load_package_before:
+        _ = list(walk_package(load_package_before))
+    subclasses_set: set[T] = {cls}
+    subclasses_set.update(cls.__subclasses__())
+    for subclass in cls.__subclasses__():
+        subclasses_set.update(get_all_subclasses(subclass))
+    if load_package_before is not None:
+        # remove all not in the package
+        subclasses_set = {
+            subclass
+            for subclass in subclasses_set
+            if load_package_before.__name__ in subclass.__module__
+        }
+    if discard_parents:
+        subclasses_set = discard_parent_classes(subclasses_set)
+    return subclasses_set
+
+
+def get_all_nonabstract_subclasses[T: type](
+    cls: T,
+    load_package_before: ModuleType | None = None,
+    *,
+    discard_parents: bool = False,
+) -> set[T]:
+    """Find all concrete (non-abstract) subclasses of a class.
+
+    Similar to `get_all_subclasses`, but filters out abstract classes
+    (those with unimplemented abstract methods). This is the primary
+    function used by pyrig to discover implementations of ConfigFile,
+    Builder, and other extensible base classes.
+
+    Args:
+        cls: The base class to find subclasses of.
+        load_package_before: Optional package to walk before discovery.
+            See `get_all_subclasses` for details.
+        discard_parents: If True, keeps only leaf classes when a parent
+            and child are both present.
+
+    Returns:
+        A set of all non-abstract subclasses.
+
+    Example:
+        >>> from abc import ABC, abstractmethod
+        >>> class Base(ABC):
+        ...     @abstractmethod
+        ...     def method(self): pass
+        >>> class Concrete(Base):
+        ...     def method(self): pass
+        >>> get_all_nonabstract_subclasses(Base)
+        {Concrete}
+    """
+    return {
+        subclass
+        for subclass in get_all_subclasses(
+            cls,
+            load_package_before=load_package_before,
+            discard_parents=discard_parents,
+        )
+        if not inspect.isabstract(subclass)
+    }
+
+
+def init_all_nonabstract_subclasses[T: type](
+    cls: T,
+    load_package_before: ModuleType | None = None,
+    *,
+    discard_parents: bool = False,
+) -> None:
+    """Discover and instantiate all concrete subclasses of a class.
+
+    Finds all non-abstract subclasses and calls their default constructor
+    (no arguments). This is used by pyrig's ConfigFile and Builder systems
+    to automatically initialize all discovered implementations.
+
+    Args:
+        cls: The base class to find and instantiate subclasses of.
+        load_package_before: Optional package to walk before discovery.
+        discard_parents: If True, only instantiates leaf classes.
+
+    Note:
+        All subclasses must have a no-argument `__init__` or be classes
+        that can be called with no arguments (e.g., using `__init_subclass__`
+        or `__new__` for initialization).
+    """
+    for subclass in get_all_nonabstract_subclasses(
+        cls,
+        load_package_before=load_package_before,
+        discard_parents=discard_parents,
+    ):
+        subclass()
+
+
+def get_all_nonabst_subcls_from_mod_in_all_deps_depen_on_dep[T: type](
+    cls: T,
+    dep: ModuleType,
+    load_package_before: ModuleType,
+    *,
+    discard_parents: bool = False,
+) -> list[T]:
+    """Find non-abstract subclasses across all packages depending on a dependency.
+
+    This is the core discovery function for pyrig's multi-package architecture.
+    It finds all packages that depend on `dep`, looks for the same relative
+    module path as `load_package_before` in each, and discovers subclasses
+    of `cls` in those modules.
+
+    For example, if `dep` is smth and `load_package_before` is
+    `smth.dev.configs`, this will find `myapp.dev.configs` in any package
+    that depends on smth, and discover ConfigFile subclasses there.
+
+    Args:
+        cls: The base class to find subclasses of.
+        dep: The dependency package that other packages depend on (e.g., pyrig or smth).
+        load_package_before: The module path within `dep` to use as a template
+            for finding equivalent modules in dependent packages.
+        discard_parents: If True, keeps only leaf classes when inheritance
+            chains span multiple packages.
+
+    Returns:
+        A list of all discovered non-abstract subclasses. Classes from the
+        same module are grouped together, but ordering between packages
+        depends on the dependency graph traversal order.
+
+    Example:
+        >>> # Find all ConfigFile implementations across the ecosystem
+        >>> subclasses = get_all_nonabst_subcls_from_mod_in_all_deps_depen_on_dep(
+        ...     ConfigFile,
+        ...     smth,
+        ...     smth.dev.configs,
+        ...     discard_parents=True
+        ... )
+    """
+    from pyrig.src.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_same_modules_from_deps_depen_on_dep,
+    )
+
+    subclasses: list[T] = []
+    for pkg in get_same_modules_from_deps_depen_on_dep(load_package_before, dep):
+        subclasses.extend(
+            get_all_nonabstract_subclasses(
+                cls,
+                load_package_before=pkg,
+                discard_parents=discard_parents,
+            )
+        )
+    # as these are different modules and pks we need to discard parents again
+    if discard_parents:
+        subclasses = discard_parent_classes(subclasses)
+    return subclasses
+
+
+@overload
+def discard_parent_classes[T: type](classes: list[T]) -> list[T]: ...
+
+
+@overload
+def discard_parent_classes[T: type](classes: set[T]) -> set[T]: ...
+
+
+def discard_parent_classes[T: type](
+    classes: list[T] | set[T],
+) -> list[T] | set[T]:
+    """Remove parent classes when their children are also present.
+
+    Filters a collection of classes to keep only "leaf" classes - those
+    that have no subclasses in the collection. This enables clean override
+    behavior: if you subclass a ConfigFile, only your subclass will be used.
+
+    Args:
+        classes: A list or set of class types to filter. Modified in place.
+
+    Returns:
+        The same collection with parent classes removed. The return type
+        matches the input type (list or set).
+
+    Example:
+        >>> class A: pass
+        >>> class B(A): pass
+        >>> class C(B): pass
+        >>> discard_parent_classes({A, B, C})
+        {C}
+        >>> discard_parent_classes([A, C])  # B not in list, so A stays
+        [A, C]
+    """
+    for cls in classes.copy():
+        if any(child in classes for child in cls.__subclasses__()):
+            classes.remove(cls)
+    return classes

pyrig/src/modules/function.py

@@ -0,0 +1,189 @@
+"""Function detection and extraction utilities.
+
+This module provides utilities for identifying callable objects and extracting
+functions from modules. It handles the various forms that "functions" can take
+in Python, including plain functions, methods, staticmethods, classmethods,
+properties, and decorated functions.
+
+These utilities are used by pyrig to discover CLI subcommands from modules
+and to extract testable functions for automatic test skeleton generation.
+
+Example:
+    >>> from pyrig.src.modules.function import get_all_functions_from_module
+    >>> import my_module
+    >>> functions = get_all_functions_from_module(my_module)
+    >>> [f.__name__ for f in functions]
+    ['func_a', 'func_b', 'func_c']
+"""
+
+import inspect
+from collections.abc import Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+from pyrig.src.modules.inspection import get_def_line, get_obj_members
+
+
+def is_func_or_method(obj: Any) -> bool:
+    """Check if an object is a plain function or bound method.
+
+    This is a basic check using `inspect.isfunction` and `inspect.ismethod`.
+    For a more comprehensive check that includes staticmethods, classmethods,
+    and properties, use `is_func()` instead.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a function or bound method, False otherwise.
+
+    Note:
+        This does NOT detect staticmethod/classmethod descriptors or properties.
+        Use `is_func()` for those cases.
+    """
+    return inspect.isfunction(obj) or inspect.ismethod(obj)
+
+
+def is_func(obj: Any) -> bool:
+    """Check if an object is any kind of callable method-like attribute.
+
+    Provides comprehensive detection of callable objects as they appear in
+    class bodies or modules. This includes:
+        - Plain functions (which become instance methods in classes)
+        - staticmethod descriptors
+        - classmethod descriptors
+        - property descriptors (the getter is considered a method)
+        - Decorated functions with a `__wrapped__` chain
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a method-like callable, False otherwise.
+
+    Example:
+        >>> class MyClass:
+        ...     def method(self): pass
+        ...     @staticmethod
+        ...     def static(): pass
+        ...     @property
+        ...     def prop(self): return 1
+        >>> is_func(MyClass.method)
+        True
+        >>> is_func(MyClass.__dict__['static'])
+        True
+        >>> is_func(MyClass.prop)
+        True
+    """
+    if is_func_or_method(obj):
+        return True
+
+    if isinstance(obj, (staticmethod, classmethod, property)):
+        return True
+
+    unwrapped = inspect.unwrap(obj)
+
+    return is_func_or_method(unwrapped)
+
+
+def get_all_functions_from_module(
+    module: ModuleType | str, *, include_annotate: bool = False
+) -> list[Callable[..., Any]]:
+    """Extract all functions defined directly in a module.
+
+    Retrieves all function objects that are defined in the specified module,
+    excluding functions imported from other modules. Functions are returned
+    sorted by their definition order (line number in source).
+
+    This is used by pyrig to discover CLI subcommands and to generate test
+    skeletons for module-level functions.
+
+    Args:
+        module: The module to extract functions from. Can be a module object
+            or a module name string.
+        include_annotate: If False (default), excludes `__annotate__` methods
+            introduced in Python 3.14. These are internal and not user-defined.
+
+    Returns:
+        A list of callable functions defined in the module, sorted by their
+        definition order in the source file.
+
+    Example:
+        >>> import my_module
+        >>> funcs = get_all_functions_from_module(my_module)
+        >>> [f.__name__ for f in funcs]
+        ['first_function', 'second_function', 'third_function']
+    """
+    from pyrig.src.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_module_of_obj,
+    )
+
+    if isinstance(module, str):
+        module = import_module(module)
+    funcs = [
+        func
+        for _name, func in get_obj_members(module, include_annotate=include_annotate)
+        if is_func(func)
+        if get_module_of_obj(func).__name__ == module.__name__
+    ]
+    # sort by definition order
+    return sorted(funcs, key=get_def_line)
+
+
+def unwrap_method(method: Any) -> Callable[..., Any] | Any:
+    """Unwrap a method to its underlying function object.
+
+    Handles staticmethod/classmethod descriptors (extracts `__func__`),
+    properties (extracts the getter), and decorated functions (follows
+    the `__wrapped__` chain).
+
+    Args:
+        method: The method-like object to unwrap. Can be a function,
+            staticmethod, classmethod, property, or decorated callable.
+
+    Returns:
+        The underlying unwrapped function object.
+
+    Example:
+        >>> class MyClass:
+        ...     @staticmethod
+        ...     def static_method():
+        ...         pass
+        >>> raw_descriptor = MyClass.__dict__['static_method']
+        >>> unwrap_method(raw_descriptor).__name__
+        'static_method'
+    """
+    if isinstance(method, (staticmethod, classmethod)):
+        method = method.__func__
+    if isinstance(method, property):
+        method = method.fget
+    return inspect.unwrap(method)
+
+
+def is_abstractmethod(method: Any) -> bool:
+    """Check if a method is marked as abstract.
+
+    Detects methods decorated with `@abstractmethod` (or variants like
+    `@abstractclassmethod`, `@abstractproperty`). Handles wrapped methods
+    by unwrapping them first.
+
+    Args:
+        method: The method to check. Can be wrapped in staticmethod,
+            classmethod, property, or decorators.
+
+    Returns:
+        True if the method has `__isabstractmethod__` set to True,
+        False otherwise.
+
+    Example:
+        >>> from abc import ABC, abstractmethod
+        >>> class MyABC(ABC):
+        ...     @abstractmethod
+        ...     def must_implement(self):
+        ...         pass
+        >>> is_abstractmethod(MyABC.must_implement)
+        True
+    """
+    method = unwrap_method(method)
+    return getattr(method, "__isabstractmethod__", False)

pyrig/src/modules/inspection.py

@@ -0,0 +1,148 @@
+"""Low-level inspection utilities for Python object introspection.
+
+This module provides foundational utilities for inspecting Python objects,
+particularly focused on unwrapping decorated methods and accessing object
+metadata. These utilities handle edge cases like properties, staticmethods,
+classmethods, and decorator chains.
+
+The module also provides detection for PyInstaller frozen bundles, where
+some inspection operations behave differently or are unavailable.
+
+Example:
+    >>> from pyrig.src.modules.inspection import get_def_line, get_unwrapped_obj
+    >>> class MyClass:
+    ...     @property
+    ...     def value(self):
+    ...         return 42
+    >>> get_def_line(MyClass.value)
+    3
+"""
+
+import inspect
+import sys
+from collections.abc import Callable
+from typing import Any, cast
+
+
+def get_obj_members(
+    obj: Any, *, include_annotate: bool = False
+) -> list[tuple[str, Any]]:
+    """Get all members of an object as name-value pairs.
+
+    Retrieves all attributes of an object using `inspect.getmembers()`,
+    optionally filtering out Python 3.14+ annotation-related methods
+    that are typically not relevant for introspection.
+
+    Args:
+        obj: The object to inspect (typically a class or module).
+        include_annotate: If False (default), excludes `__annotate__` and
+            `__annotate_func__` methods introduced in Python 3.14. These
+            are internal methods for deferred annotation evaluation.
+
+    Returns:
+        A list of (name, value) tuples for each member of the object.
+    """
+    members = [(member, value) for member, value in inspect.getmembers(obj)]
+    if not include_annotate:
+        members = [
+            (member, value)
+            for member, value in members
+            if member not in ("__annotate__", "__annotate_func__")
+        ]
+    return members
+
+
+def inside_frozen_bundle() -> bool:
+    """Check if the code is running inside a PyInstaller frozen bundle.
+
+    PyInstaller sets `sys.frozen` to True when running from a bundled
+    executable. Some inspection operations (like `getsourcelines`) are
+    unavailable in frozen bundles.
+
+    Returns:
+        True if running inside a frozen PyInstaller bundle, False otherwise.
+    """
+    return getattr(sys, "frozen", False)
+
+
+def get_def_line(obj: Any) -> int:
+    """Get the source line number where an object is defined.
+
+    Handles various callable types including plain functions, methods,
+    properties, staticmethods, classmethods, and decorated functions.
+    Used for sorting functions/methods in definition order.
+
+    Args:
+        obj: A callable object (function, method, property, etc.).
+
+    Returns:
+        The 1-based line number where the object is defined in its source
+        file. Returns 0 if running in a frozen bundle where source is
+        unavailable.
+
+    Note:
+        For properties, returns the line where the getter is defined.
+        Automatically unwraps decorator chains to find the original function.
+    """
+    if isinstance(obj, property):
+        obj = obj.fget
+    unwrapped = inspect.unwrap(obj)
+    if hasattr(unwrapped, "__code__"):
+        return int(unwrapped.__code__.co_firstlineno)
+    # getsourcelines does not work if in a pyinstaller bundle or something
+    if inside_frozen_bundle():
+        return 0
+    return inspect.getsourcelines(unwrapped)[1]
+
+
+def get_unwrapped_obj(obj: Any) -> Any:
+    """Unwrap a method-like object to its underlying function.
+
+    Handles properties (extracts the getter), staticmethod/classmethod
+    descriptors, and decorator chains. Useful for accessing the actual
+    function object when you need to inspect its attributes.
+
+    Args:
+        obj: A callable object that may be wrapped (property, staticmethod,
+            classmethod, or decorated function).
+
+    Returns:
+        The underlying unwrapped function object.
+
+    Example:
+        >>> class MyClass:
+        ...     @staticmethod
+        ...     def static_method():
+        ...         pass
+        >>> unwrapped = get_unwrapped_obj(MyClass.__dict__['static_method'])
+        >>> unwrapped.__name__
+        'static_method'
+    """
+    if isinstance(obj, property):
+        obj = obj.fget  # get the getter function of the property
+    return inspect.unwrap(obj)
+
+
+def get_qualname_of_obj(obj: Callable[..., Any] | type) -> str:
+    """Get the qualified name of a callable or type.
+
+    The qualified name includes the class name for methods (e.g.,
+    "MyClass.my_method") and handles wrapped/decorated objects.
+
+    Args:
+        obj: A callable (function, method) or type (class) to get the
+            qualified name of.
+
+    Returns:
+        The qualified name string (e.g., "ClassName.method_name" for
+        methods, "function_name" for module-level functions).
+
+    Example:
+        >>> class MyClass:
+        ...     def my_method(self):
+        ...         pass
+        >>> get_qualname_of_obj(MyClass.my_method)
+        'MyClass.my_method'
+    """
+    unwrapped = get_unwrapped_obj(obj)
+    return cast("str", unwrapped.__qualname__)