pyrig 2.2.6__py3-none-any.whl

pyrig/src/modules/module.py

@@ -0,0 +1,658 @@
+"""Module loading, path conversion, and cross-package discovery utilities.
+
+This module provides comprehensive utilities for working with Python modules,
+including bidirectional path/module name conversion, dynamic module creation,
+object importing, and cross-package module discovery.
+
+Key capabilities:
+    - Path conversion: Convert between filesystem paths and module names
+    - Module creation: Create new modules with proper package structure
+    - Object importing: Import objects from fully qualified import paths
+    - Cross-package discovery: Find equivalent modules across dependent packages
+
+The cross-package discovery (`get_same_modules_from_deps_depen_on_dep`) is
+central to pyrig's multi-package architecture, enabling automatic discovery
+of ConfigFile implementations and other extensible components across all
+packages that depend on pyrig.
+
+Example:
+    >>> from pyrig.src.modules.module import to_module_name, to_path
+    >>> to_module_name("src/package/module.py")
+    'src.package.module'
+    >>> to_path("src.package.module", is_package=False)
+    PosixPath('src/package/module.py')
+"""
+
+import importlib.util
+import inspect
+import logging
+import os
+import sys
+from collections.abc import Callable, Sequence
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from pyrig.src.modules.class_ import (
+    get_all_cls_from_module,
+    get_all_methods_from_cls,
+)
+from pyrig.src.modules.function import get_all_functions_from_module
+from pyrig.src.modules.inspection import (
+    get_qualname_of_obj,
+    get_unwrapped_obj,
+)
+from pyrig.src.modules.package import (
+    DependencyGraph,
+    get_modules_and_packages_from_package,
+    import_pkg_from_path,
+    module_is_package,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_module_content_as_str(module: ModuleType) -> str:
+    """Retrieve the complete source code of a module as a string.
+
+    This function locates the physical file associated with the given module object
+    and reads its entire content. It works for both regular modules and packages
+    by determining the correct path using module_to_path.
+
+    Args:
+        module: The module object whose source code should be retrieved
+
+
+    Returns:
+        The complete source code of the module as a string
+
+    """
+    path = to_path(module, is_package=False)
+    return path.read_text(encoding="utf-8")
+
+
+def to_module_name(path: str | Path | ModuleType) -> str:
+    """Convert a filesystem path to a Python module import name.
+
+    Transforms a file or directory path into the corresponding Python module name
+    by making it relative to the current directory, removing the file extension,
+    and replacing directory separators with dots.
+
+    Args:
+        path: a str that represents a path or a Path object or a ModuleType object
+                or a str that represents a module name
+
+    Returns:
+        The Python module name corresponding to the path
+
+    Example:
+        path_to_module_name("src/package/module.py") -> "src.package.module"
+
+    """
+    if isinstance(path, ModuleType):
+        return path.__name__
+    if isinstance(path, Path):
+        cwd = (
+            Path.cwd()
+            if not getattr(sys, "frozen", False)
+            else Path(getattr(sys, "_MEIPASS", ""))
+        )
+        if path.is_absolute():
+            path = path.relative_to(cwd)
+        if path.suffix:
+            path = path.with_suffix("")
+        # return joined on . parts
+        return ".".join(path.parts)
+    if path in (".", "./", ""):
+        return ""
+    # we get a str that can either be a dotted module name or a path
+    # e.g. package/module.py or package/module or
+    # package.module or just package/package2
+    # or just package with nothing
+    path = path.removesuffix(".py")
+    if "." in path:
+        # already a module name
+        return path
+    return to_module_name(Path(path))
+
+
+def to_path(module_name: str | ModuleType | Path, *, is_package: bool) -> Path:
+    """Convert a Python module import name to its filesystem path.
+
+    Transforms a Python module name into the corresponding file path by replacing
+    dots with directory separators and adding the .py extension. Uses the
+    package_name_to_path function for the directory structure.
+
+    Args:
+        module_name: A Python module name to convert or Path or ModuleType
+        is_package: Whether to return the path to the package directory
+            without the .py extension
+
+    Returns:
+        A Path object representing the filesystem path to the module
+        if is_package is True, returns the path to the package directory
+        without the .py extension
+
+    Example:
+        module_name_to_path("src.package.module") -> Path("src/package/module.py")
+
+    """
+    if isinstance(module_name, ModuleType) and hasattr(module_name, "__file__"):
+        file_str = module_name.__file__
+        if file_str is not None:
+            file_path = Path(file_str)
+            if is_package:
+                # this way if you want __init__ in the path then package=False
+                file_path = file_path.parent
+            return file_path
+    module_name = to_module_name(module_name)
+    path = Path(module_name.replace(".", os.sep))
+    # for smth like pyinstaller we support frozen path
+    if getattr(sys, "frozen", False):
+        path = Path(getattr(sys, "_MEIPASS", "")) / path
+    # if path is cwd or "."
+    if path in (Path.cwd(), Path()):
+        return Path()
+    # if path without with.py exists
+    with_py = path.with_suffix(".py")
+    if with_py.exists():
+        return with_py
+    not_with_py = path.with_suffix("")
+    if not_with_py.exists():
+        return not_with_py
+    if is_package:
+        return path
+    return path.with_suffix(".py")
+
+
+def make_dir_with_init_file(path: Path) -> None:
+    """Create a directory and add __init__.py files to make it a package.
+
+    Args:
+        path: The directory path to create and initialize as a package
+
+    """
+    path.mkdir(parents=True, exist_ok=True)
+    make_init_modules_for_package(path)
+
+
+def create_module(
+    module_name: str | Path | ModuleType, *, is_package: bool
+) -> ModuleType:
+    """Create a new Python module file and import it.
+
+    Creates a new module file at the location specified by the module name,
+    ensuring all necessary parent directories and __init__.py files exist.
+    Optionally writes content to the module file and parent __init__.py files.
+    Finally imports and returns the newly created module.
+
+    Args:
+        module_name: The fully qualified name of the module to create
+        is_package: Whether to create a package instead of a module
+
+    Returns:
+        The imported module object representing the newly created module
+
+    Note:
+        Includes a small delay (0.1s) before importing to ensure filesystem operations
+        are complete, preventing race conditions.
+
+    """
+    path = to_path(module_name, is_package=is_package)
+    if path == Path():
+        msg = f"Cannot create module {module_name=} because it is the CWD"
+        logger.error(msg)
+        raise ValueError(msg)
+
+    make_dir_with_init_file(path if is_package else path.parent)
+
+    if not path.exists() and not is_package:
+        path.write_text(get_default_module_content())
+    return import_module_from_file(path)
+
+
+def import_module_from_file(path: Path | str) -> ModuleType:
+    """Import a module from a filesystem path.
+
+    Converts the path to a module name and imports it. Handles both regular
+    modules (.py files) and packages (directories with __init__.py).
+
+    Args:
+        path: Filesystem path to the module or package. Can be a Path object
+            or a string path.
+
+    Returns:
+        The imported module object.
+
+    Raises:
+        FileNotFoundError: If the path does not exist.
+        ValueError: If the module cannot be loaded.
+    """
+    module_name = to_module_name(path)
+    path = to_path(module_name, is_package=False)
+    module = import_module_with_default(module_name)
+    if module is not None:
+        return module
+    if path.is_dir():
+        return import_pkg_from_path(path)
+    return import_module_from_path(path)
+
+
+def import_module_from_file_with_default(
+    path: Path, default: Any = None
+) -> ModuleType | Any:
+    """Import a module from a path, returning a default on failure.
+
+    Args:
+        path: Filesystem path to the module.
+        default: Value to return if the module cannot be imported.
+
+    Returns:
+        The imported module, or `default` if import fails.
+    """
+    try:
+        return import_module_from_file(path)
+    except FileNotFoundError:
+        return default
+
+
+def import_module_from_path(path: Path) -> ModuleType:
+    """Import a module directly from a .py file.
+
+    Uses `importlib.util` to create a module spec and load the module
+    from the specified file. The module is registered in `sys.modules`
+    with a name derived from its path relative to the current directory.
+
+    Args:
+        path: Path to the .py file to import.
+
+    Returns:
+        The imported module object.
+
+    Raises:
+        ValueError: If a module spec or loader cannot be created for the path.
+    """
+    # name is dotted path relative to cwd
+    name = to_module_name(path.resolve().relative_to(Path.cwd()))
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None:
+        msg = f"Could not create spec for {path}"
+        raise ValueError(msg)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    if spec.loader is None:
+        msg = f"Could not create loader for {path}"
+        raise ValueError(msg)
+    spec.loader.exec_module(module)
+    return module
+
+
+def make_obj_importpath(obj: Callable[..., Any] | type | ModuleType) -> str:
+    """Create a fully qualified import path string for a Python object.
+
+    Generates the import path that would be used to import the given object.
+    Handles different types of objects (modules, classes, functions) appropriately.
+
+    Args:
+        obj: The object (module, class, or function) to create an import path for
+
+    Returns:
+        A string representing the fully qualified import path for the object
+
+    Examples:
+        For a module: "package.subpackage.module"
+        For a class: "package.module.ClassName"
+        For a function: "package.module.function_name"
+        For a method: "package.module.ClassName.method_name"
+
+    """
+    if isinstance(obj, ModuleType):
+        return obj.__name__
+    module: str | None = get_module_of_obj(obj).__name__
+    obj_name = get_qualname_of_obj(obj)
+    if not module:
+        return obj_name
+    return module + "." + obj_name
+
+
+def import_obj_from_importpath(
+    importpath: str,
+) -> Callable[..., Any] | type | ModuleType:
+    """Import a Python object (module, class, or function) from its import path.
+
+    Attempts to import the object specified by the given import path. First tries
+    to import it as a module, and if that fails, attempts to import it as a class
+    or function by splitting the path and using getattr.
+
+    Args:
+        importpath: The fully qualified import path of the object
+
+    Returns:
+        The imported object (module, class, or function)
+
+    Raises:
+        ImportError: If the module part of the path cannot be imported
+        AttributeError: If the object is not found in the module
+
+    """
+    try:
+        return import_module(importpath)
+    except ImportError:
+        # might be a class or function
+        if "." not in importpath:
+            raise
+        module_name, obj_name = importpath.rsplit(".", 1)
+        module = import_module(module_name)
+        obj: Callable[..., Any] | type = getattr(module, obj_name)
+        return obj
+
+
+def get_isolated_obj_name(obj: Callable[..., Any] | type | ModuleType) -> str:
+    """Extract the bare name of an object without its module prefix.
+
+    Retrieves just the name part of an object, without any module path information.
+    For modules, returns the last component of the module path.
+
+    Args:
+        obj: The object (module, class, or function) to get the name for
+
+    Returns:
+        The isolated name of the object without any module path
+
+    Examples:
+        For a module "package.subpackage.module": returns "module"
+        For a class: returns the class name
+        For a function: returns the function name
+
+    """
+    obj = get_unwrapped_obj(obj)
+    if isinstance(obj, ModuleType):
+        return obj.__name__.split(".")[-1]
+    if isinstance(obj, type):
+        return obj.__name__
+    return get_qualname_of_obj(obj).split(".")[-1]
+
+
+def get_objs_from_obj(
+    obj: Callable[..., Any] | type | ModuleType,
+) -> Sequence[Callable[..., Any] | type | ModuleType]:
+    """Extract all contained objects from a container object.
+
+    Retrieves all relevant objects contained within the given object, with behavior
+    depending on the type of the container:
+    - For modules: returns all functions and classes defined in the module
+    - For packages: returns all submodules in the package
+    - For classes: returns all methods defined directly in the class
+    - For other objects: returns an empty list
+
+    Args:
+        obj: The container object to extract contained objects from
+
+    Returns:
+        A sequence of objects contained within the given container object
+
+    """
+    if isinstance(obj, ModuleType):
+        if module_is_package(obj):
+            return get_modules_and_packages_from_package(obj)[1]
+        objs: list[Callable[..., Any] | type] = []
+        objs.extend(get_all_functions_from_module(obj))
+        objs.extend(get_all_cls_from_module(obj))
+        return objs
+    if isinstance(obj, type):
+        return get_all_methods_from_cls(obj, exclude_parent_methods=True)
+    return []
+
+
+def execute_all_functions_from_module(module: ModuleType) -> list[Any]:
+    """Execute all functions defined in a module with no arguments.
+
+    Retrieves all functions defined in the module and calls each one with no arguments.
+    Collects and returns the results of all function calls.
+
+    Args:
+        module: The module containing functions to execute
+
+    Returns:
+        A list containing the return values from all executed functions
+
+    Note:
+        Only executes functions defined directly in the module, not imported functions.
+        All functions must accept being called with no arguments.
+
+    """
+    return [f() for f in get_all_functions_from_module(module)]
+
+
+def get_default_init_module_content() -> str:
+    """Generate standardized content for an __init__.py file.
+
+    Creates a simple docstring for an __init__.py file based on its location,
+    following the project's documentation conventions.
+
+    Args:
+        path: The path to the __init__.py file or its parent directory
+
+    Returns:
+        A string containing a properly formatted docstring for the __init__.py file
+
+    """
+    return '''"""__init__ module."""
+'''
+
+
+def get_default_module_content() -> str:
+    """Generate standardized content for a Python module file.
+
+    Creates a simple docstring for a module file based on its name,
+    following the project's documentation conventions.
+
+    Returns:
+        A string containing a properly formatted docstring for the module file
+
+    """
+    return '''"""module."""
+'''
+
+
+def get_module_of_obj(obj: Any, default: ModuleType | None = None) -> ModuleType:
+    """Return the module name where a method-like object is defined.
+
+    Args:
+        obj: Method-like object (funcs, method, property, staticmethod, classmethod...)
+        default: Default module to return if the module cannot be determined
+
+    Returns:
+        The module name as a string, or None if module cannot be determined.
+
+    """
+    unwrapped = get_unwrapped_obj(obj)
+    module = inspect.getmodule(unwrapped)
+    if not module:
+        msg = f"Could not determine module of {obj}"
+        if default:
+            return default
+        raise ValueError(msg)
+    return module
+
+
+def get_executing_module() -> ModuleType:
+    """Get the module where execution has started.
+
+    The executing module is the module that contains the __main__ attribute as __name__
+    E.g. if you run `python -m pyrig.setup` from the command line,
+    then the executing module is pyrigmodules.setup
+
+    Returns:
+        The module where execution has started
+
+    Raises:
+        ValueError: If no __main__ module is found or if the executing module
+                    cannot be determined
+
+    """
+    main = sys.modules.get("__main__")
+    if main is None:
+        msg = "No __main__ module found"
+        raise ValueError(msg)
+    return main
+
+
+def import_module_with_default(
+    module_name: str, default: Any = None
+) -> ModuleType | Any:
+    """Import a module, returning a default if the module cannot be imported.
+
+    Args:
+        module_name: Name of the module to import
+        default: Default module to return if the module cannot be imported
+
+    Returns:
+        The imported module, or the default module if the module cannot be imported
+
+    Raises:
+        ValueError: If the module cannot be imported
+
+    """
+    try:
+        return import_module(module_name)
+    except ImportError:
+        logger.debug("Could not import module %s", module_name)
+        return default
+
+
+def make_init_module(path: Path) -> None:
+    """Create an __init__.py file in the specified directory.
+
+    Creates an __init__.py file with default content in the given directory,
+    making it a proper Python package.
+
+    Args:
+        path: The directory path where the __init__.py file should be created
+
+    Note:
+        If the path already points to an __init__.py file, that file will be
+        overwritten with the default content.
+        Creates parent directories if they don't exist.
+
+    """
+    init_path = path / "__init__.py"
+
+    if init_path.exists():
+        return
+
+    content = get_default_init_module_content()
+    init_path.write_text(content)
+
+
+def make_init_modules_for_package(path: Path) -> None:
+    """Create __init__.py files in all subdirectories of a package.
+
+    Ensures that all subdirectories of the given package have __init__.py files,
+    effectively converting them into proper Python packages. Skips directories
+    that match patterns in .gitignore.
+
+    Args:
+        path: The package path or module object to process
+
+    Note:
+        Does not modify directories that already have __init__.py files.
+        Uses the default content for __init__.py files
+        from get_default_init_module_content.
+
+    """
+    # create init files in all subdirectories and in the root
+    make_init_module(path)
+    for p in path.rglob("*"):
+        if p.is_dir():
+            make_init_module(p)
+
+
+def make_pkg_dir(path: Path) -> None:
+    """Create __init__.py files in all parent directories of a path.
+
+    It does not include the CWD.
+
+    Args:
+        path: The path to create __init__.py files for
+
+    Note:
+        Does not modify directories that already have __init__.py files.
+        Uses the default content for __init__.py files
+        from get_default_init_module_content.
+
+    """
+    if path.is_absolute():
+        path = path.relative_to(Path.cwd())
+    # mkdir all parents
+    path.mkdir(parents=True, exist_ok=True)
+
+    make_init_module(path)
+    for p in path.parents:
+        if p in (Path.cwd(), Path()):
+            continue
+        make_init_module(p)
+
+
+def get_same_modules_from_deps_depen_on_dep(
+    module: ModuleType, dep: ModuleType, until_pkg: ModuleType | None = None
+) -> list[ModuleType]:
+    """Find equivalent modules across all packages depending on a dependency.
+
+    This is a key function for pyrig's multi-package architecture. Given a
+    module path within a dependency (e.g.,  smth.dev.configs`), it finds
+    the equivalent module path in all packages that depend on that dependency
+    (e.g., `myapp.dev.configs`, `other_pkg.dev.configs`).
+
+    This enables automatic discovery of ConfigFile implementations, Builder
+    subclasses, and other extensible components across the entire ecosystem
+    of packages that depend on pyrig.
+
+    Args:
+        module: The module to use as a template (e.g., `smth.dev.configs`).
+        dep: The dependency package that other packages depend on (e.g., pyrig or smth).
+        until_pkg: Optional package to stop at. If provided, only modules from
+            packages that depend on `until_pkg` will be returned.
+
+    Returns:
+        A list of equivalent modules from all packages that depend on `dep`,
+        including the original module itself.
+
+    Example:
+        >>> import smth
+        >>> from smth.dev import configs
+        >>> modules = get_same_modules_from_deps_depen_on_dep(
+        ...     configs, smth
+        ... )
+        >>> [m.__name__ for m in modules]
+        ['smth.dev.configs', 'myapp.dev.configs', 'other_pkg.dev.configs']
+    """
+    module_name = module.__name__
+    graph = DependencyGraph()
+    pkgs = graph.get_all_depending_on(dep, include_self=True)
+
+    modules: list[ModuleType] = []
+    for pkg in pkgs:
+        pkg_module_name = module_name.replace(dep.__name__, pkg.__name__, 1)
+        pkg_module = import_module_from_file(pkg_module_name)
+        modules.append(pkg_module)
+        if isinstance(until_pkg, ModuleType) and pkg.__name__ == until_pkg.__name__:
+            break
+    return modules
+
+
+def get_module_name_replacing_start_module(
+    module: ModuleType, new_start_module_name: str
+) -> str:
+    """Replace the root module name in a module's fully qualified name.
+
+    Args:
+        module: The module whose name to transform.
+        new_start_module_name: The new root module name.
+
+    Returns:
+        The transformed module name.
+    """
+    module_current_start = module.__name__.split(".")[0]
+    return module.__name__.replace(module_current_start, new_start_module_name, 1)