winipedia-utils 0.1.0__py3-none-any.whl

winipedia_utils/modules/module.py

@@ -0,0 +1,361 @@
+"""Module utilities for introspection and manipulation.
+
+This module provides comprehensive utility functions for working with Python modules,
+including path conversions, module creation, object importing, and content extraction.
+It handles the complexities of Python's module system by providing a consistent API
+for module operations across different contexts (packages vs. standalone modules).
+
+The utilities support both runtime module manipulation and static analysis,
+making them suitable for code generation, testing frameworks, and dynamic imports.
+"""
+
+import inspect
+import os
+import time
+from collections.abc import Callable, Sequence
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import Any, cast
+
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.modules.class_ import (
+    get_all_cls_from_module,
+    get_all_methods_from_cls,
+)
+from winipedia_utils.modules.function import get_all_functions_from_module
+from winipedia_utils.modules.package import (
+    get_modules_and_packages_from_package,
+    make_dir_with_init_file,
+    module_is_package,
+)
+
+logger = get_logger(__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()
+
+
+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):
+        rel_path = path.relative_to(".")
+        if rel_path.suffix:
+            rel_path = rel_path.with_suffix("")
+        # return joined on . parts
+        return ".".join(rel_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")
+
+    """
+    module_name = to_module_name(module_name)
+    path = Path(module_name.replace(".", os.sep))
+    if is_package:
+        return path
+    return path.with_suffix(".py")
+
+
+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 current directory"
+        logger.error(msg)
+        raise ValueError(msg)
+
+    make_dir_with_init_file(path if is_package else path.parent)
+    # create the module file if not exists
+    if not path.exists() and not is_package:
+        path.write_text(get_default_module_content())
+
+    module_name = to_module_name(path)
+    # wait before importing the module
+    time.sleep(0.1)
+    return import_module(module_name)
+
+
+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
+        module_name, obj_name = importpath.rsplit(".", 1)
+        module = import_module(module_name)
+        obj: Callable[..., Any] | type | ModuleType = 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_def_line(obj: Any) -> int:
+    """Return the line number where a method-like object is defined."""
+    if isinstance(obj, property):
+        obj = obj.fget
+    unwrapped = inspect.unwrap(obj)
+    return inspect.getsourcelines(unwrapped)[1]
+
+
+def get_module_of_obj(obj: Any) -> ModuleType:
+    """Return the module name where a method-like object is defined.
+
+    Args:
+        obj: Method-like object (funcs, method, property, staticmethod, classmethod...)
+
+    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}"
+        raise ValueError(msg)
+    return module
+
+
+def get_qualname_of_obj(obj: Callable[..., Any] | type) -> str:
+    """Return the name of a method-like object."""
+    unwrapped = get_unwrapped_obj(obj)
+    return cast("str", unwrapped.__qualname__)
+
+
+def get_unwrapped_obj(obj: Any) -> Any:
+    """Return the unwrapped version of a method-like object."""
+    if isinstance(obj, property):
+        obj = obj.fget  # get the getter function of the property
+    return inspect.unwrap(obj)

winipedia_utils/modules/package.py

@@ -0,0 +1,350 @@
+"""Package utilities for introspection and manipulation.
+
+This module provides comprehensive utility functions for working with Python packages,
+including package discovery, creation, traversal, and module extraction. It handles
+both regular packages and namespace packages, offering tools for filesystem operations
+and module imports related to package structures.
+
+The utilities support both static package analysis and dynamic package manipulation,
+making them suitable for code generation, testing frameworks, and package management.
+"""
+
+import os
+import pkgutil
+from collections.abc import Generator, Iterable
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+
+from setuptools import find_namespace_packages as _find_namespace_packages
+from setuptools import find_packages as _find_packages
+
+from winipedia_utils.git.gitignore import walk_os_skipping_gitignore_patterns
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_scr_package() -> ModuleType:
+    """Identify and return the main source package of the project.
+
+    Discovers the main source package by finding all top-level packages
+    and filtering out the test package. This is useful for automatically
+    determining the package that contains the actual implementation code.
+
+    Returns:
+        The main source package as a module object
+
+    Raises:
+        StopIteration: If no source package can be found or
+                       if only the test package exists
+
+    """
+    from winipedia_utils.testing.convention import TESTS_PACKAGE_NAME
+
+    packages = find_packages_as_modules(depth=0)
+    return next(p for p in packages if p.__name__ != TESTS_PACKAGE_NAME)
+
+
+def make_dir_with_init_file(path: str | Path) -> None:
+    """Create a directory and initialize it as a Python package.
+
+    Creates the specified directory (including any necessary parent directories)
+    and adds __init__.py files to make it a proper Python package. Optionally
+    writes custom content to the __init__.py file.
+
+    Args:
+        path: The directory path to create and initialize as a package
+
+    Note:
+        If the directory already exists, it will not be modified, but __init__.py
+        files will still be added if missing.
+
+    """
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    make_init_modules_for_package(path)
+
+
+def module_is_package(obj: ModuleType) -> bool:
+    """Determine if a module object represents a package.
+
+    Checks if the given module object is a package by looking for the __path__
+    attribute, which is only present in package modules.
+
+    Args:
+        obj: The module object to check
+
+    Returns:
+        True if the module is a package, False otherwise
+
+    Note:
+        This works for both regular packages and namespace packages.
+
+    """
+    return hasattr(obj, "__path__")
+
+
+def package_name_to_path(package_name: str | Path | ModuleType) -> Path:
+    """Convert a Python package import name to its filesystem path.
+
+    Transforms a Python package name (with dots) into the corresponding
+    directory path by replacing dots with the appropriate directory separator
+    for the current operating system.
+
+    Args:
+        package_name: A Python package name to convert
+                      or a Path object or a ModuleType object
+
+    Returns:
+        A Path object representing the filesystem path to the package
+
+    Example:
+        package_name_to_path("package.subpackage") -> Path("package/subpackage")
+
+    """
+    if isinstance(package_name, ModuleType):
+        package_name = package_name.__name__
+    elif isinstance(package_name, Path):
+        package_name = package_name.as_posix()
+    return Path(package_name.replace(".", os.sep))
+
+
+def get_modules_and_packages_from_package(
+    package: ModuleType,
+) -> tuple[list[ModuleType], list[ModuleType]]:
+    """Extract all direct subpackages and modules from a package.
+
+    Discovers and imports all direct child modules and subpackages within
+    the given package. Returns them as separate lists.
+
+    Args:
+        package: The package module to extract subpackages and modules from
+
+    Returns:
+        A tuple containing (list of subpackages, list of modules)
+
+    Note:
+        Only includes direct children, not recursive descendants.
+        All discovered modules and packages are imported during this process.
+
+    """
+    packages: list[ModuleType] = []
+    modules: list[ModuleType] = []
+    for _, name, is_pkg in pkgutil.iter_modules(
+        package.__path__, prefix=package.__name__ + "."
+    ):
+        mod = import_module(name)
+        if is_pkg:
+            packages.append(mod)
+        else:
+            modules.append(mod)
+
+    return packages, modules
+
+
+def find_packages(
+    *,
+    depth: int | None = None,
+    include_namespace_packages: bool = False,
+    where: str = ".",
+    exclude: Iterable[str] = (),
+    include: Iterable[str] = ("*",),
+) -> list[str]:
+    """Discover Python packages in the specified directory.
+
+    Finds all Python packages in the given directory, with options to filter
+    by depth, include/exclude patterns, and namespace packages. This is a wrapper
+    around setuptools' find_packages and find_namespace_packages functions with
+    additional filtering capabilities.
+
+    Args:
+        depth: Optional maximum depth of package nesting to include (None for unlimited)
+        include_namespace_packages: Whether to include namespace packages
+        where: Directory to search for packages (default: current directory)
+        exclude: Patterns of package names to exclude
+        include: Patterns of package names to include
+
+    Returns:
+        A list of package names as strings
+
+    Example:
+        find_packages(depth=1) might return ["package1", "package2"]
+
+    """
+    if include_namespace_packages:
+        package_names = _find_namespace_packages(
+            where=where, exclude=exclude, include=include
+        )
+    else:
+        package_names = _find_packages(where=where, exclude=exclude, include=include)
+
+    # Convert to list of strings explicitly
+    package_names_list: list[str] = list(map(str, package_names))
+
+    if depth is not None:
+        package_names_list = [p for p in package_names_list if p.count(".") <= depth]
+
+    return package_names_list
+
+
+def find_packages_as_modules(
+    *,
+    depth: int | None = None,
+    include_namespace_packages: bool = False,
+    where: str = ".",
+    exclude: Iterable[str] = (),
+    include: Iterable[str] = ("*",),
+) -> list[ModuleType]:
+    """Discover and import Python packages in the specified directory.
+
+    Similar to find_packages, but imports and returns the actual module objects
+    instead of just the package names.
+
+    Args:
+        depth: Optional maximum depth of package nesting to include (None for unlimited)
+        include_namespace_packages: Whether to include namespace packages
+        where: Directory to search for packages (default: current directory)
+        exclude: Patterns of package names to exclude
+        include: Patterns of package names to include
+
+    Returns:
+        A list of imported package module objects
+
+    Note:
+        All discovered packages are imported during this process.
+
+    """
+    package_names = find_packages(
+        depth=depth,
+        include_namespace_packages=include_namespace_packages,
+        where=where,
+        exclude=exclude,
+        include=include,
+    )
+    return [import_module(package_name) for package_name in package_names]
+
+
+def walk_package(
+    package: ModuleType,
+) -> Generator[tuple[ModuleType, list[ModuleType]], None, None]:
+    """Recursively walk through a package and all its subpackages.
+
+    Performs a depth-first traversal of the package hierarchy, yielding each
+    package along with its direct module children.
+
+    Args:
+        package: The root package module to start walking from
+
+    Yields:
+        Tuples of (package, list of modules in package)
+
+    Note:
+        All packages and modules are imported during this process.
+        The traversal is depth-first, so subpackages are fully processed
+        before moving to siblings.
+
+    """
+    subpackages, submodules = get_modules_and_packages_from_package(package)
+    yield package, submodules
+    for subpackage in subpackages:
+        yield from walk_package(subpackage)
+
+
+def make_init_modules_for_package(path: str | Path | ModuleType) -> 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.
+
+    """
+    from winipedia_utils.modules.module import to_path
+
+    path = to_path(path, is_package=True)
+
+    for root, _dirs, files in walk_os_skipping_gitignore_patterns(path):
+        if "__init__.py" in files:
+            continue
+        make_init_module(root)
+
+
+def make_init_module(path: str | 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.
+
+    """
+    from winipedia_utils.modules.module import get_default_init_module_content, to_path
+
+    path = to_path(path, is_package=True)
+
+    # if __init__.py not in path add it
+    if path.name != "__init__.py":
+        path = path / "__init__.py"
+
+    content = get_default_init_module_content()
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+def copy_package(
+    src_package: ModuleType,
+    dst: str | Path | ModuleType,
+    *,
+    with_file_content: bool = True,
+) -> None:
+    """Copy a package to a different destination.
+
+    Takes a ModuleType of package and a destination package name and then copies
+    the package to the destination. If with_file_content is True, it copies the
+    content of the files, otherwise it just creates the files.
+
+    Args:
+        src_package (ModuleType): The package to copy
+        dst (str | Path): destination package name as a
+                          Path with / or as a str with dots
+        with_file_content (bool, optional): copies the content of the files.
+
+    """
+    from winipedia_utils.modules.module import (
+        create_module,
+        get_isolated_obj_name,
+        get_module_content_as_str,
+        to_path,
+    )
+
+    src_path = to_path(src_package, is_package=True)
+    dst_path = to_path(dst, is_package=True) / get_isolated_obj_name(src_package)
+    for package, modules in walk_package(src_package):
+        # we need to make right path from the package to the dst
+        # so that if we have a package package.package2.package3
+        # and dst is a path like package4/package5/package6
+        # we get the right path which is package4/package5/package6/package3
+        package_path = to_path(package, is_package=True)
+        dst_package_path = dst_path / package_path.relative_to(src_path)
+        create_module(dst_package_path, is_package=True)
+        for module in modules:
+            module_name = get_isolated_obj_name(module)
+            module_path = dst_package_path / module_name
+            create_module(module_path, is_package=False)
+            if with_file_content:
+                module_path.write_text(get_module_content_as_str(module))