winipedia-utils 0.2.63__py3-none-any.whl → 0.6.6__py3-none-any.whl

winipedia_utils/git/pre_commit/run_hooks.py

@@ -15,11 +15,10 @@ from winipedia_utils.os.os import run_subprocess
 logger = get_logger(__name__)
 
 
-def _run_all_hooks() -> None:
+def run_hooks() -> None:
     """Import all funcs defined in hooks.py and runs them."""
     hook_funcs = get_all_functions_from_module(hooks)
 
-    exit_code = 0
     for hook_func in hook_funcs:
         subprocess_args = hook_func()
         result = run_subprocess(
@@ -28,22 +27,30 @@ def _run_all_hooks() -> None:
         passed = result.returncode == 0
 
         log_method = logger.info
-        passed_str = (f"{GREEN}PASSED" if passed else f"{RED}FAILED") + RESET
+        status_str = (f"{GREEN}PASSED" if passed else f"{RED}FAILED") + RESET
         if not passed:
             log_method = logger.error
-            passed_str += f"\n{result.stdout}"
-            exit_code = 1
+            status_str += f"""
+---------------------------------------------------------------------------------------------
+Stdout:
+
+{result.stdout}
+
+---------------------------------------------------------------------------------------------
+Stderr:
+
+{result.stderr}
+
+---------------------------------------------------------------------------------------------
+"""
+
         # make the dashes always the same lentgth by adjusting to len of hook name
         num_dashes = 50 - len(hook_func.__name__)
         log_method(
             "Hook %s -%s> %s",
             hook_func.__name__,
             "-" * num_dashes,
-            passed_str,
+            status_str,
         )
-
-    sys.exit(exit_code)
-
-
-if __name__ == "__main__":
-    _run_all_hooks()
+        if not passed:
+            sys.exit(1)

winipedia_utils/iterating/iterate.py

@@ -5,7 +5,7 @@ including getting the length of an iterable with a default value.
 These utilities help with iterable operations and manipulations.
 """
 
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from typing import Any
 
 
@@ -27,3 +27,65 @@ def get_len_with_default(iterable: Iterable[Any], default: int | None = None) ->
             msg = "Can't get length of iterable and no default value provided"
             raise TypeError(msg) from e
         return default
+
+
+def nested_structure_is_subset(
+    subset: dict[Any, Any] | list[Any] | Any,
+    superset: dict[Any, Any] | list[Any] | Any,
+    on_false_dict_action: Callable[[dict[Any, Any], dict[Any, Any], Any], Any]
+    | None = None,
+    on_false_list_action: Callable[[list[Any], list[Any], int], Any] | None = None,
+) -> bool:
+    """Check if a dictionary is a nested subset of another dictionary.
+
+    Args:
+        subset: Dictionary to check
+        superset: Dictionary to check against
+        on_false_dict_action: Action to take on each false dict comparison
+            must return a bool to indicate if after action is still false
+        on_false_list_action: Action to take on each false list comparison
+            must return a bool to indicate if after action is still false
+
+    Each value of a key must be equal to the value of the same key in the superset.
+    If the value is dictionary, the function is called recursively.
+    If the value is list, each item must be in the list of the same key in the superset.
+    The order in lists does not matter.
+
+    Returns:
+        True if subset is a nested subset of superset, False otherwise
+    """
+    if isinstance(subset, dict) and isinstance(superset, dict):
+        iterable: Iterable[tuple[Any, Any]] = subset.items()
+        on_false_action: Callable[[Any, Any, Any], Any] | None = on_false_dict_action
+
+        def get_actual(key_or_index: Any) -> Any:
+            """Get actual value from superset."""
+            return superset.get(key_or_index)
+
+    elif isinstance(subset, list) and isinstance(superset, list):
+        iterable = enumerate(subset)
+        on_false_action = on_false_list_action
+
+        def get_actual(key_or_index: Any) -> Any:
+            """Get actual value from superset."""
+            subset_val = subset[key_or_index]
+            for superset_val in superset:
+                if nested_structure_is_subset(subset_val, superset_val):
+                    return superset_val
+
+            return superset[key_or_index] if key_or_index < len(superset) else None
+    else:
+        return subset == superset
+
+    all_good = True
+    for key_or_index, value in iterable:
+        actual_value = get_actual(key_or_index)
+        if not nested_structure_is_subset(
+            value, actual_value, on_false_dict_action, on_false_list_action
+        ):
+            all_good = False
+            if on_false_action is not None:
+                on_false_action(subset, superset, key_or_index)
+                all_good = nested_structure_is_subset(subset, superset)
+
+    return all_good

winipedia_utils/modules/class_.py

@@ -13,10 +13,14 @@ from types import ModuleType
 from typing import Any
 
 from winipedia_utils.modules.function import is_func
+from winipedia_utils.modules.inspection import get_def_line, get_obj_members
 
 
 def get_all_methods_from_cls(
-    class_: type, *, exclude_parent_methods: bool = False
+    class_: type,
+    *,
+    exclude_parent_methods: bool = False,
+    include_annotate: bool = False,
 ) -> list[Callable[..., Any]]:
     """Get all methods from a class.
 
@@ -27,14 +31,21 @@ def get_all_methods_from_cls(
         class_: The class to extract methods from
         exclude_parent_methods: If True, only include methods defined in this class,
         excluding those inherited from parent classes
+        include_annotate: If False, exclude __annotate__ method
+        introduced in Python 3.14, defaults to False
+
     Returns:
         A list of callable methods from the class
 
     """
-    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+    from winipedia_utils.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_module_of_obj,
+    )
 
     methods = [
-        (method, name) for name, method in inspect.getmembers(class_) if is_func(method)
+        (method, name)
+        for name, method in get_obj_members(class_, include_annotate=include_annotate)
+        if is_func(method)
     ]
 
     if exclude_parent_methods:
@@ -63,7 +74,9 @@ def get_all_cls_from_module(module: ModuleType | str) -> list[type]:
         A list of class types defined in the module
 
     """
-    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+    from winipedia_utils.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_module_of_obj,
+    )
 
     if isinstance(module, str):
         module = import_module(module)
@@ -79,7 +92,9 @@ def get_all_cls_from_module(module: ModuleType | str) -> list[type]:
     return sorted(classes, key=get_def_line)
 
 
-def get_all_subclasses(cls: type) -> list[type]:
+def get_all_subclasses(
+    cls: type, load_package_before: ModuleType | None = None
+) -> set[type]:
     """Get all subclasses of a class.
 
     Retrieves all classes that are subclasses of the specified class.
@@ -87,18 +102,37 @@ def get_all_subclasses(cls: type) -> list[type]:
 
     Args:
         cls: The class to find subclasses of
+        load_package_before: If provided,
+        walks the package before loading the subclasses
+        This is useful when the subclasses are defined in other modules that need
+        to be imported before they can be found by __subclasses__
 
     Returns:
         A list of subclasses of the given class
 
     """
+    from winipedia_utils.modules.package import (  # noqa: PLC0415  # avoid circular import
+        walk_package,
+    )
+
+    if load_package_before:
+        _ = list(walk_package(load_package_before))
     subclasses_set = set(cls.__subclasses__())
     for subclass in cls.__subclasses__():
         subclasses_set.update(get_all_subclasses(subclass))
-    return list(subclasses_set)
-
-
-def get_all_nonabstract_subclasses(cls: type) -> list[type]:
+    if load_package_before is not None:
+        # remove all not in the package
+        subclasses_set = {
+            subclass
+            for subclass in subclasses_set
+            if subclass.__module__.startswith(load_package_before.__name__)
+        }
+    return subclasses_set
+
+
+def get_all_nonabstract_subclasses(
+    cls: type, load_package_before: ModuleType | None = None
+) -> set[type]:
     """Get all non-abstract subclasses of a class.
 
     Retrieves all classes that are subclasses of the specified class,
@@ -107,13 +141,36 @@ def get_all_nonabstract_subclasses(cls: type) -> list[type]:
 
     Args:
         cls: The class to find subclasses of
+        load_package_before: If provided,
+        walks the package before loading the subclasses
+        This is useful when the subclasses are defined in other modules that need
+        to be imported before they can be found by __subclasses__
 
     Returns:
         A list of non-abstract subclasses of the given class
 
     """
-    return [
+    return {
         subclass
-        for subclass in get_all_subclasses(cls)
+        for subclass in get_all_subclasses(cls, load_package_before=load_package_before)
         if not inspect.isabstract(subclass)
-    ]
+    }
+
+
+def init_all_nonabstract_subclasses(
+    cls: type, load_package_before: ModuleType | None = None
+) -> None:
+    """Initialize all non-abstract subclasses of a class.
+
+    Args:
+        cls: The class to find subclasses of
+        load_package_before: If provided,
+        walks the package before loading the subclasses
+        This is useful when the subclasses are defined in other modules that need
+        to be imported before they can be found by __subclasses__
+
+    """
+    for subclass in get_all_nonabstract_subclasses(
+        cls, load_package_before=load_package_before
+    ):
+        subclass()

winipedia_utils/modules/function.py

@@ -12,6 +12,8 @@ from importlib import import_module
 from types import ModuleType
 from typing import Any
 
+from winipedia_utils.modules.inspection import get_def_line, get_obj_members
+
 
 def is_func_or_method(obj: Any) -> bool:
     """Return True if *obj* is a function or method.
@@ -57,7 +59,9 @@ def is_func(obj: Any) -> bool:
     return is_func_or_method(unwrapped)
 
 
-def get_all_functions_from_module(module: ModuleType | str) -> list[Callable[..., Any]]:
+def get_all_functions_from_module(
+    module: ModuleType | str, *, include_annotate: bool = False
+) -> list[Callable[..., Any]]:
     """Get all functions defined in a module.
 
     Retrieves all function objects that are defined directly in the specified module,
@@ -66,18 +70,23 @@ def get_all_functions_from_module(module: ModuleType | str) -> list[Callable[...
 
     Args:
         module: The module to extract functions from
+        include_annotate: If False, exclude __annotate__ method
+        introduced in Python 3.14, defaults to False
 
     Returns:
         A list of callable functions defined in the module
 
     """
-    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+    from winipedia_utils.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 inspect.getmembers(module, is_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
@@ -99,3 +108,17 @@ def unwrap_method(method: Any) -> Callable[..., Any] | Any:
     if isinstance(method, property):
         method = method.fget
     return inspect.unwrap(method)
+
+
+def is_abstractmethod(method: Any) -> bool:
+    """Check if a method is an abstract method.
+
+    Args:
+        method: The method to check
+
+    Returns:
+        True if the method is an abstract method, False otherwise
+
+    """
+    method = unwrap_method(method)
+    return getattr(method, "__isabstractmethod__", False)

winipedia_utils/modules/inspection.py

@@ -0,0 +1,56 @@
+"""Inspection utilities for introspecting Python objects.
+
+This module provides utility functions for inspecting Python objects,
+including checking if an object is a function or method, and unwrapping
+methods to their underlying functions.
+"""
+
+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."""
+    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:
+    """Return True if the code is running inside a frozen bundle."""
+    return getattr(sys, "frozen", False)
+
+
+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)
+    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:
+    """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)
+
+
+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__)

winipedia_utils/modules/module.py

@@ -17,7 +17,7 @@ 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 typing import Any
 
 from winipedia_utils.logging.logger import get_logger
 from winipedia_utils.modules.class_ import (
@@ -25,6 +25,7 @@ from winipedia_utils.modules.class_ import (
     get_all_methods_from_cls,
 )
 from winipedia_utils.modules.function import get_all_functions_from_module
+from winipedia_utils.modules.inspection import get_qualname_of_obj, get_unwrapped_obj
 from winipedia_utils.modules.package import (
     get_modules_and_packages_from_package,
     make_dir_with_init_file,
@@ -215,6 +216,8 @@ def import_obj_from_importpath(
         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 | ModuleType = getattr(module, obj_name)
@@ -327,24 +330,6 @@ def get_default_module_content() -> str:
     return '''"""module."""'''
 
 
-def inside_frozen_bundle() -> bool:
-    """Return True if the code is running inside a frozen bundle."""
-    return getattr(sys, "frozen", False)
-
-
-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)
-    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_module_of_obj(obj: Any, default: ModuleType | None = None) -> ModuleType:
     """Return the module name where a method-like object is defined.
 
@@ -366,14 +351,23 @@ def get_module_of_obj(obj: Any, default: ModuleType | None = None) -> ModuleType
     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_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 winipedia_utils.setup` from the command line,
+    then the executing module is winipedia_utils.modules.setup
 
-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)
+    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

winipedia_utils/modules/package.py

@@ -9,21 +9,23 @@ The utilities support both static package analysis and dynamic package manipulat
 making them suitable for code generation, testing frameworks, and package management.
 """
 
+import importlib.metadata
+import importlib.util
 import os
 import pkgutil
+import re
 import sys
 from collections.abc import Generator, Iterable
 from importlib import import_module
 from pathlib import Path
 from types import ModuleType
+from typing import Any
 
+import networkx as nx
 from setuptools import find_namespace_packages as _find_namespace_packages
 from setuptools import find_packages as _find_packages
 
-from winipedia_utils.git.gitignore.gitignore import (
-    load_gitignore,
-    walk_os_skipping_gitignore_patterns,
-)
+import winipedia_utils
 from winipedia_utils.logging.logger import get_logger
 
 logger = get_logger(__name__)
@@ -44,7 +46,9 @@ def get_src_package() -> ModuleType:
                        if only the test package exists
 
     """
-    from winipedia_utils.testing.convention import TESTS_PACKAGE_NAME
+    from winipedia_utils.testing.convention import (  # noqa: PLC0415  # avoid circular import
+        TESTS_PACKAGE_NAME,
+    )
 
     packages = find_packages_as_modules(depth=0)
     return next(p for p in packages if p.__name__ != TESTS_PACKAGE_NAME)
@@ -180,8 +184,13 @@ def find_packages(
         find_packages(depth=1) might return ["package1", "package2"]
 
     """
+    from winipedia_utils.git.gitignore.config import (  # noqa: PLC0415
+        GitIgnoreConfigFile,  # avoid circular import
+    )
+
     if exclude is None:
-        exclude = load_gitignore()
+        # must init GitIgnoreConfigFile to create .gitignore if it does not exist
+        exclude = GitIgnoreConfigFile.load()
         exclude = [
             p.replace("/", ".").removesuffix(".") for p in exclude if p.endswith("/")
         ]
@@ -280,7 +289,12 @@ def make_init_modules_for_package(path: str | Path | ModuleType) -> None:
         from get_default_init_module_content.
 
     """
-    from winipedia_utils.modules.module import to_path
+    from winipedia_utils.git.gitignore.gitignore import (  # noqa: PLC0415
+        walk_os_skipping_gitignore_patterns,  # avoid circular import
+    )
+    from winipedia_utils.modules.module import (  # noqa: PLC0415
+        to_path,  # avoid circular import
+    )
 
     path = to_path(path, is_package=True)
 
@@ -305,7 +319,10 @@ def make_init_module(path: str | Path) -> None:
         Creates parent directories if they don't exist.
 
     """
-    from winipedia_utils.modules.module import get_default_init_module_content, to_path
+    from winipedia_utils.modules.module import (  # noqa: PLC0415  # avoid circular import
+        get_default_init_module_content,
+        to_path,
+    )
 
     path = to_path(path, is_package=True)
 
@@ -338,7 +355,7 @@ def copy_package(
         with_file_content (bool, optional): copies the content of the files.
 
     """
-    from winipedia_utils.modules.module import (
+    from winipedia_utils.modules.module import (  # noqa: PLC0415  # avoid circular import
         create_module,
         get_isolated_obj_name,
         get_module_content_as_str,
@@ -368,7 +385,9 @@ def get_main_package() -> ModuleType:
 
     Even when this package is installed as a module.
     """
-    from winipedia_utils.modules.module import to_module_name
+    from winipedia_utils.modules.module import (  # noqa: PLC0415  # avoid circular import
+        to_module_name,
+    )
 
     main = sys.modules.get("__main__")
     if main is None:
@@ -388,3 +407,90 @@ def get_main_package() -> ModuleType:
 
     msg = "Not able to determine the main package"
     raise ValueError(msg)
+
+
+class DependencyGraph(nx.DiGraph):  # type: ignore [type-arg]
+    """A directed graph representing Python package dependencies."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the dependency graph and build it immediately."""
+        super().__init__(*args, **kwargs)
+        self.build()
+
+    def build(self) -> None:
+        """Build the graph from installed Python distributions."""
+        for dist in importlib.metadata.distributions():
+            name = self.parse_distname_from_metadata(dist)
+            self.add_node(name)
+
+            requires = dist.requires or []
+            for req in requires:
+                dep = self.parse_pkg_name_from_req(req)
+                if dep:
+                    self.add_edge(name, dep)  # package → dependency
+
+    @staticmethod
+    def parse_distname_from_metadata(dist: importlib.metadata.Distribution) -> str:
+        """Extract the distribution name from its metadata."""
+        # replace - with _ to handle packages like winipedia-utils
+        name: str = dist.metadata["Name"]
+        return DependencyGraph.normalize_package_name(name)
+
+    @staticmethod
+    def normalize_package_name(name: str) -> str:
+        """Normalize a package name."""
+        return name.lower().replace("-", "_").strip()
+
+    @staticmethod
+    def parse_pkg_name_from_req(req: str) -> str | None:
+        """Extract the bare dependency name from a requirement string."""
+        # split on the first non alphanumeric character like >, <, =, etc.
+        # keep - and _ for names like winipedia-utils or winipedia_utils
+        dep = re.split(r"[^a-zA-Z0-9_-]", req.strip())[0].strip()
+        return DependencyGraph.normalize_package_name(dep) if dep else None
+
+    def get_all_depending_on(
+        self, package: ModuleType, *, include_self: bool = False
+    ) -> set[ModuleType]:
+        """Return all packages that directly or indirectly depend on the given package.
+
+        Args:
+            package: The module whose dependents should be found.
+            include_self: Whether to include the package itself in the result.
+
+        Returns:
+            A set of imported module objects representing dependents.
+        """
+        # replace - with _ to handle packages like winipedia-utils
+        target = package.__name__.lower()
+        if target not in self:
+            msg = f"Package '{target}' not found in dependency graph"
+            raise ValueError(msg)
+
+        dependents = nx.ancestors(self, target)
+        if include_self:
+            dependents.add(target)
+
+        return self.import_packages(dependents)
+
+    @staticmethod
+    def import_packages(names: set[str]) -> set[ModuleType]:
+        """Attempt to import all module names that can be resolved."""
+        modules: set[ModuleType] = set()
+        for name in names:
+            spec = importlib.util.find_spec(name)
+            if spec is not None:
+                modules.add(importlib.import_module(name))
+        return modules
+
+    def get_all_depending_on_winipedia_utils(
+        self, *, include_winipedia_utils: bool = False
+    ) -> set[ModuleType]:
+        """Return all packages that directly or indirectly depend on winipedia_utils."""
+        if get_src_package() == winipedia_utils:
+            deps: set[ModuleType] = set()
+        else:
+            deps = self.get_all_depending_on(winipedia_utils, include_self=False)
+        if include_winipedia_utils:
+            deps.add(winipedia_utils)
+        return deps