winipedia-utils 0.1.0__py3-none-any.whl

winipedia_utils/oop/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.oop."""

winipedia_utils/oop/mixins/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.oop.mixins."""

winipedia_utils/oop/mixins/meta.py

@@ -0,0 +1,315 @@
+"""Metaclass utilities for class behavior modification and enforcement.
+
+This module provides metaclasses that can be used to
+modify class behavior at creation time.
+These metaclasses can be used individually or combined to create classes
+with enhanced capabilities and stricter implementation requirements.
+
+"""
+
+import time
+from abc import ABCMeta, abstractmethod
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, final
+
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.modules.class_ import get_all_methods_from_cls
+from winipedia_utils.modules.function import is_func
+from winipedia_utils.text.string import value_to_truncated_string
+
+logger = get_logger(__name__)
+
+
+class LoggingMeta(type):
+    """Metaclass that automatically adds logging to class methods.
+
+    Wraps non-magic methods with a logging decorator that tracks method calls,
+    arguments, execution time, and return values. Includes rate limiting to
+    prevent log flooding.
+    """
+
+    def __new__(
+        mcs: type["LoggingMeta"],
+        name: str,
+        bases: tuple[type, ...],
+        dct: dict[str, Any],
+    ) -> "LoggingMeta":
+        """Create a new class with logging-wrapped methods.
+
+        Args:
+            mcs: The metaclass instance
+            name: The name of the class being created
+            bases: The base classes of the class being created
+            dct: The attribute dictionary of the class being created
+
+        Returns:
+            A new class with logging functionality added to its methods
+
+        """
+        # Wrap all callables of the class with a logging wrapper
+
+        for attr_name, attr_value in dct.items():
+            if mcs.is_loggable_method(attr_value):
+                dct[attr_name] = mcs.wrap_with_logging(
+                    func=attr_value, class_name=name, call_times={}
+                )
+
+        return super().__new__(mcs, name, bases, dct)
+
+    @staticmethod
+    def is_loggable_method(method: Callable[..., Any]) -> bool:
+        """Determine if a method should have logging applied.
+
+        Args:
+            method: The method to check
+
+        Returns:
+            True if the method should be wrapped with logging, False otherwise
+
+        """
+        return (
+            is_func(method)  # must be a method-like attribute
+            and not method.__name__.startswith("__")  # must not be a magic method
+        )
+
+    @staticmethod
+    def wrap_with_logging(
+        func: Callable[..., Any],
+        class_name: str,
+        call_times: dict[str, float],
+    ) -> Callable[..., Any]:
+        """Wrap a function with logging functionality.
+
+        Creates a wrapper that logs method calls, arguments, execution time,
+        and return values. Includes rate limiting to prevent excessive logging.
+
+        Args:
+            func: The function to wrap with logging
+            class_name: The name of the class containing the function
+            call_times: Dictionary to track when methods were last called
+
+        Returns:
+            A wrapped function with logging capabilities
+
+        """
+        time_time = time.time  # Cache the time.time function for performance
+
+        @wraps(func)
+        def wrapper(self: object, *args: object, **kwargs: object) -> object:
+            # call_times as a dictionary to store the call times of the function
+            # we only log if the time since the last call is greater than the threshold
+            # this is to avoid spamming the logs
+
+            func_name = func.__name__
+
+            threshold = 1
+
+            last_call_time = call_times.get(func_name, 0)
+
+            current_time = time_time()
+
+            do_logging = (current_time - last_call_time) > threshold
+
+            max_log_length = 20
+
+            if do_logging:
+                args_str = value_to_truncated_string(
+                    value=args, max_length=max_log_length
+                )
+
+                kwargs_str = value_to_truncated_string(
+                    value=kwargs, max_length=max_log_length
+                )
+
+                logger.info(
+                    "%s - Calling %s with %s and %s",
+                    class_name,
+                    func_name,
+                    args_str,
+                    kwargs_str,
+                )
+
+            # Execute the function and return the result
+
+            result = func(self, *args, **kwargs)
+
+            if do_logging:
+                duration = time_time() - current_time
+
+                result_str = value_to_truncated_string(
+                    value=result, max_length=max_log_length
+                )
+
+                logger.info(
+                    "%s - %s finished with %s seconds -> returning %s",
+                    class_name,
+                    func_name,
+                    duration,
+                    result_str,
+                )
+
+            # save the call time for the next call
+
+            call_times[func_name] = current_time
+
+            return result
+
+        return wrapper
+
+
+class ImplementationMeta(type):
+    """Metaclass that enforces implementation.
+
+    Ensures that concrete subclasses properly implement all required attributes
+    and that their types match the expected types from type annotations.
+    Additionally enforces that methods must be decorated with either @final or
+    @abstractmethod to make design intentions explicit.
+    """
+
+    def __init__(
+        cls: "ImplementationMeta",
+        name: str,
+        bases: tuple[type, ...],
+        dct: dict[str, Any],
+    ) -> None:
+        """Initialize a class with implementation checking.
+
+        Verifies that concrete classes (non-abstract) properly implement
+        all required attributes with the correct types. Also checks that
+        methods are properly decorated with @final or @abstractmethod.
+
+        Args:
+            cls: The class being initialized
+            name: The name of the class
+            bases: The base classes
+            dct: The attribute dictionary
+
+        Raises:
+            NotImplementedError: If the class doesn't define __abstract__
+            ValueError: If a required attribute is not implemented
+            TypeError: If an implemented attribute has the wrong type
+            TypeError: If a method is neither final nor abstract
+
+        """
+        super().__init__(name, bases, dct)
+
+        # Check method decorators regardless of abstract status
+
+        cls.check_method_decorators()
+
+        if cls.is_abstract_cls():
+            return
+
+        cls.check_attrs_implemented()
+
+    def is_abstract_cls(cls) -> bool:
+        """Check if the class is abstract.
+
+        Determines abstractness based on if any methods have @abstractmethod.
+
+        Returns:
+            True if the class is abstract, False otherwise
+
+        """
+        return any(cls.is_abstract_method(method) for method in cls.__dict__.values())
+
+    def check_method_decorators(cls) -> None:
+        """Check that all methods are properly decorated with @final or @abstractmethod.
+
+        Verifies that all methods in the class are explicitly marked
+        as either final or abstract to enforce design intentions.
+
+        Raises:
+            TypeError: If a method is neither final nor abstract
+
+        """
+        # Get all methods defined in this class (not inherited)
+
+        for func in get_all_methods_from_cls(cls, exclude_parent_methods=True):
+            # Check if the method is marked as final or abstract
+
+            if not cls.is_final_method(func) and not cls.is_abstract_method(func):
+                msg = (
+                    f"Method {cls.__name__}.{func.__name__} must be decorated with "
+                    f"@{final.__name__} or @{abstractmethod.__name__} "
+                    f"to make design intentions explicit."
+                )
+
+                raise TypeError(msg)
+
+    @staticmethod
+    def is_final_method(method: Callable[..., Any]) -> bool:
+        """Check if a method is marked as final.
+
+        Args:
+            method: The method to check
+
+        Returns:
+            True if the method is marked with @final, False otherwise
+
+        """
+        return getattr(method, "__final__", False)
+
+    @staticmethod
+    def is_abstract_method(method: Callable[..., Any]) -> bool:
+        """Check if a method is an abstract method.
+
+        Args:
+            method: The method to check
+
+        Returns:
+            True if the method is marked with @abstractmethod, False otherwise
+
+        """
+        return getattr(method, "__isabstractmethod__", False)
+
+    def check_attrs_implemented(cls) -> None:
+        """Check that all required attributes are implemented.
+
+        Verifies that all attributes marked as NotImplemented in parent classes
+        are properly implemented in this class, and that their types match
+        the expected types from type annotations.
+
+        Raises:
+            ValueError: If a required attribute is not implemented
+
+        """
+        for attr in cls.attrs_to_implement():
+            value = getattr(cls, attr, NotImplemented)
+
+            if value is NotImplemented:
+                msg = f"{attr=} must be implemented."
+
+                raise ValueError(msg)
+
+    def attrs_to_implement(cls) -> list[str]:
+        """Find all attributes marked as NotImplemented in parent classes.
+
+        Searches the class hierarchy for attributes that are set to NotImplemented,
+        which indicates they must be implemented by concrete subclasses.
+
+        Returns:
+            List of attribute names that must be implemented
+
+        """
+        attrs = {
+            attr
+            for base_class in cls.__mro__
+            for attr in dir(base_class)
+            if getattr(base_class, attr, None) is NotImplemented
+        }
+
+        return list(attrs)
+
+
+class ABCImplementationLoggingMeta(ImplementationMeta, LoggingMeta, ABCMeta):
+    """Combined metaclass that merges implementation, logging, and ABC functionality.
+
+    This metaclass combines the features of:
+    - ImplementationMeta: Enforces implementation of required attributes
+    - LoggingMeta: Adds automatic logging to methods
+    - ABCMeta: Provides abstract base class functionality
+
+    Use this metaclass when you need all three behaviors in a single class.
+    """

winipedia_utils/oop/mixins/mixin.py

@@ -0,0 +1,28 @@
+"""Mixin utilities for class composition and behavior extension.
+
+This module provides metaclasses and mixins that facilitate class composition
+through the mixin pattern. It includes utilities for:
+- Automatic method logging with performance tracking
+- Abstract class implementation enforcement with type checking
+- Combined metaclasses that merge multiple behaviors
+
+These utilities help create robust class hierarchies with proper implementation
+enforcement and built-in logging capabilities.
+"""
+
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.oop.mixins.meta import ABCImplementationLoggingMeta
+
+logger = get_logger(__name__)
+
+
+class ABCImplementationLoggingMixin(metaclass=ABCImplementationLoggingMeta):
+    """mixin class that provides implementation, logging, and ABC functionality.
+
+    This mixin can be used as a base class for other mixins that need:
+    - Abstract method declaration (from ABC)
+    - Implementation enforcement (from ImplementationMeta)
+    - Automatic method logging (from LoggingMeta)
+
+    Subclasses must set __abstract__ = False when they provide concrete implementations.
+    """

winipedia_utils/os/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.os."""

winipedia_utils/os/os.py

@@ -0,0 +1,61 @@
+"""OS utilities for finding commands and paths.
+
+This module provides utility functions for working with the operating system,
+including finding the path to commands and managing environment variables.
+These utilities help with system-level operations and configuration.
+"""
+
+import shutil
+import subprocess  # nosec: B404
+from pathlib import Path
+from typing import Any
+
+
+def which_with_raise(cmd: str) -> str:
+    """Give the path to the given command.
+
+    Args:
+        cmd: The command to find
+
+    Returns:
+        The path to the command
+
+    Raises:
+        FileNotFoundError: If the command is not found
+
+    """
+    path = shutil.which(cmd)
+    if path is None:
+        msg = f"Command {cmd} not found"
+        raise FileNotFoundError(msg)
+    return path
+
+
+def run_subprocess(
+    args: list[str | Path],
+    *,
+    input_: str | bytes | None = None,
+    capture_output: bool = True,
+    timeout: int | None = None,
+    check: bool = True,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[Any]:
+    """Run a subprocess.
+
+    Args:
+        args: The arguments to pass to the subprocess
+        input_: The input to pass to the subprocess
+        capture_output: Whether to capture the output of the subprocess
+        timeout: The timeout for the subprocess
+        check: to raise an exception if the subprocess returns a non-zero exit code
+        kwargs: Any other arguments to pass to subprocess.run()
+
+    """
+    return subprocess.run(  # noqa: S603  # nosec: B603
+        args,
+        check=check,
+        input=input_,
+        capture_output=capture_output,
+        timeout=timeout,
+        **kwargs,
+    )

winipedia_utils/projects/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.projects."""

winipedia_utils/projects/poetry/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.projects.poetry."""

winipedia_utils/projects/poetry/config.py

@@ -0,0 +1,91 @@
+"""Config utilities for poetry and pyproject.toml."""
+
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from tomlkit.toml_document import TOMLDocument
+
+from winipedia_utils.projects.poetry.poetry import logger
+
+
+def laod_pyproject_toml() -> TOMLDocument:
+    """Load the pyproject.toml file."""
+    return tomlkit.parse(Path("pyproject.toml").read_text())
+
+
+def dump_pyproject_toml(toml: TOMLDocument) -> None:
+    """Dump the pyproject.toml file."""
+    with Path("pyproject.toml").open("w") as f:
+        tomlkit.dump(toml, f)
+
+
+def get_poetry_package_name() -> str:
+    """Get the name of the project from pyproject.toml."""
+    toml = laod_pyproject_toml()
+    project_dict = toml.get("project", {})
+    project_name = str(project_dict.get("name", ""))
+    return project_name.replace("-", "_")
+
+
+def _get_pyproject_toml_tool_configs() -> dict[str, Any]:
+    """Get the tool configurations for pyproject.toml."""
+    return {
+        "ruff": {
+            "exclude": [".*"],
+            "lint": {
+                "select": ["ALL"],
+                "ignore": ["D203", "D213", "COM812", "ANN401"],
+                "fixable": ["ALL"],
+                "pydocstyle": {
+                    "convention": "google",
+                },
+            },
+        },
+        "mypy": {
+            "strict": True,
+            "warn_unreachable": True,
+            "show_error_codes": True,
+            "files": ".",
+        },
+        "pytest": {
+            "ini_options": {
+                "testpaths": ["tests"],
+            }
+        },
+        "bandit": {},
+    }
+
+
+def _tool_config_is_correct(tool: str, config: dict[str, Any]) -> bool:
+    """Check if the tool configuration in pyproject.toml is correct."""
+    toml = laod_pyproject_toml()
+    actual_tools = toml.get("tool", {})
+
+    return bool(actual_tools.get(tool) == config)
+
+
+def _pyproject_tool_configs_are_correct() -> bool:
+    """Check if the tool configurations in pyproject.toml are correct."""
+    expected_tool_dict = _get_pyproject_toml_tool_configs()
+    for tool, config in expected_tool_dict.items():
+        if not _tool_config_is_correct(tool, config):
+            return False
+
+    return True
+
+
+def _add_tool_configurations_to_pyproject_toml() -> None:
+    """Add tool.* configurations to pyproject.toml."""
+    expected_tool_dict = _get_pyproject_toml_tool_configs()
+    toml = laod_pyproject_toml()
+    actual_tool_dict = toml.get("tool", {})
+    # update the toml dct and dump it but only update the tools specified not all tools
+    for tool, config in expected_tool_dict.items():
+        # if tool section already exists skip it
+        if not _tool_config_is_correct(tool, config):
+            logger.info("Adding tool.%s configuration to pyproject.toml", tool)
+            # updates inplace of toml_dict["tool"][tool]
+            actual_tool_dict[tool] = config
+
+    dump_pyproject_toml(toml)

winipedia_utils/projects/poetry/poetry.py

@@ -0,0 +1,30 @@
+"""Project utilities for introspection and manipulation.
+
+This module provides utility functions for working with Python projects
+"""
+
+import sys
+
+from winipedia_utils.consts import _DEV_DEPENDENCIES
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.os.os import run_subprocess, which_with_raise
+
+logger = get_logger(__name__)
+
+POETRY_PATH = which_with_raise("poetry")
+
+POETRY_RUN_ARGS = [POETRY_PATH, "run"]
+
+POETRY_ADD_ARGS = [POETRY_PATH, "add"]
+
+POETRY_ADD_DEV_ARGS = [*POETRY_ADD_ARGS, "--group", "dev"]
+
+POETRY_RUN_PYTHON_ARGS = [*POETRY_RUN_ARGS, sys.executable]
+
+POETRY_RUN_RUFF_ARGS = [*POETRY_RUN_ARGS, "ruff"]
+
+
+def _install_dev_dependencies() -> None:
+    """Install winipedia_utils dev dependencies as dev dependencies."""
+    logger.info("Adding dev dependencies: %s", _DEV_DEPENDENCIES)
+    run_subprocess([*POETRY_ADD_DEV_ARGS, *_DEV_DEPENDENCIES], check=True)

winipedia_utils/setup.py

@@ -0,0 +1,36 @@
+"""A script that can be called after you installed the package.
+
+This script calls create tests, creates the pre-commit config, and
+creates the pyproject.toml file and some other things to set up a project.
+This package assumes you are using poetry and pre-commit.
+This script is intended to be called once at the beginning of a project.
+"""
+
+from winipedia_utils.git.pre_commit.config import _add_package_hook_to_pre_commit_config
+from winipedia_utils.git.pre_commit.run_hooks import _run_all_hooks
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.projects.poetry.config import (
+    _add_tool_configurations_to_pyproject_toml,
+)
+from winipedia_utils.projects.poetry.poetry import (
+    _install_dev_dependencies,
+)
+
+logger = get_logger(__name__)
+
+
+def _setup() -> None:
+    """Set up the project."""
+    # install winipedia_utils dev dependencies as dev
+    _install_dev_dependencies()
+    # create pre-commit config
+    _add_package_hook_to_pre_commit_config()
+    # add tool.* configurations to pyproject.toml
+    _add_tool_configurations_to_pyproject_toml()
+    # run pre-commit once, create tests is included here
+    _run_all_hooks()
+    logger.info("Setup complete!")
+
+
+if __name__ == "__main__":
+    _setup()

winipedia_utils/testing/__init__.py

@@ -0,0 +1 @@
+"""__init__ module for winipedia_utils.testing."""

winipedia_utils/testing/assertions.py

@@ -0,0 +1,23 @@
+"""Testing assertion utilities for enhanced test validation.
+
+This module provides custom assertion functions that extend Python's built-in
+assert statement with additional features like improved error messages and
+specialized validation logic for common testing scenarios.
+"""
+
+
+def assert_with_msg(expr: bool, msg: str) -> None:  # noqa: FBT001
+    """Assert that an expression is true with a custom error message.
+
+    A thin wrapper around Python's built-in assert statement that makes it
+    easier to provide meaningful error messages when assertions fail.
+
+    Args:
+        expr: The expression to evaluate for truthiness
+        msg: The error message to display if the assertion fails
+
+    Raises:
+        AssertionError: If the expression evaluates to False
+
+    """
+    assert expr, msg  # noqa: S101  # nosec: B101