winipedia-utils 0.1.0__py3-none-any.whl

winipedia_utils/git/gitignore.py

@@ -0,0 +1,80 @@
+"""Git utilities for file and directory operations.
+
+This module provides utility functions for working with Git repositories,
+including checking if paths are in .gitignore and walking directories
+while respecting gitignore patterns. These utilities help with file operations
+that need to respect Git's ignore rules.
+"""
+
+import os
+from collections.abc import Generator
+from pathlib import Path
+
+import pathspec
+
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def path_is_in_gitignore(relative_path: str | Path) -> bool:
+    """Check if a path matches any pattern in the .gitignore file.
+
+    Args:
+        relative_path: The path to check, relative to the repository root
+
+    Returns:
+        True if the path matches any pattern in .gitignore, False otherwise
+
+    """
+    as_path = Path(relative_path)
+    is_dir = (
+        bool(as_path.suffix == "") or as_path.is_dir() or str(as_path).endswith(os.sep)
+    )
+    is_dir = is_dir and not as_path.is_file()
+
+    as_posix = as_path.as_posix()
+    if is_dir and not as_posix.endswith("/"):
+        as_posix += "/"
+
+    gitignore_path = Path(".gitignore")
+    if not gitignore_path.exists():
+        return False  # No ignore rules
+
+    spec = pathspec.PathSpec.from_lines(
+        "gitwildmatch", gitignore_path.read_text().splitlines()
+    )
+
+    return spec.match_file(as_posix)
+
+
+def walk_os_skipping_gitignore_patterns(
+    folder: str | Path = ".",
+) -> Generator[tuple[Path, list[str], list[str]], None, None]:
+    """Walk a directory tree while skipping paths that match gitignore patterns.
+
+    Similar to os.walk, but skips directories and files that match patterns
+    in the .gitignore file.
+
+    Args:
+        folder: The root directory to start walking from
+
+    Yields:
+        Tuples of (current_path, directories, files) for each directory visited
+
+    """
+    folder = Path(folder)
+    for root, dirs, files in os.walk(folder):
+        rel_root = Path(root).relative_to(".")
+
+        # skip all in patterns in .gitignore
+        if path_is_in_gitignore(rel_root):
+            logger.info("Skipping %s because it is in .gitignore", rel_root)
+            dirs.clear()
+            continue
+
+        # remove all files that match patterns in .gitignore
+        valid_files = [f for f in files if not path_is_in_gitignore(rel_root / f)]
+        valid_dirs = [d for d in dirs if not path_is_in_gitignore(rel_root / d)]
+
+        yield rel_root, valid_dirs, valid_files

winipedia_utils/git/pre_commit/__init__.py

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

winipedia_utils/git/pre_commit/config.py

@@ -0,0 +1,60 @@
+"""Has config utilities for pre-commit."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def load_pre_commit_config() -> dict[str, Any]:
+    """Load the pre-commit config."""
+    path = Path(".pre-commit-config.yaml")
+    if not path.exists():
+        path.touch()
+    return yaml.safe_load(path.read_text()) or {}
+
+
+def dump_pre_commit_config(config: dict[str, Any]) -> None:
+    """Dump the pre-commit config."""
+    path = Path(".pre-commit-config.yaml")
+    with path.open("w") as f:
+        yaml.safe_dump(config, f, sort_keys=False)
+
+
+def _get_pre_commit_config_dict() -> dict[str, Any]:
+    """Get the content for a pre-commit config file as a dictionary."""
+    return {
+        "repo": "local",
+        "hooks": [
+            {
+                "id": "winipedia-utils",
+                "name": "winipedia-utils",
+                "entry": "python -m winipedia_utils.git.pre_commit.run_hooks",
+                "language": "system",
+                "always_run": True,
+                "pass_filenames": False,
+            }
+        ],
+    }
+
+
+def _pre_commit_config_is_correct() -> bool:
+    """Check if the pre-commit config is correct."""
+    config = load_pre_commit_config()
+    package_hook_config = _get_pre_commit_config_dict()
+    return bool(config.get("repos", [{}])[0] == package_hook_config)
+
+
+def _add_package_hook_to_pre_commit_config() -> None:
+    """Add the winipedia-utils hook to the pre-commit config."""
+    config = load_pre_commit_config()
+    package_hook_config = _get_pre_commit_config_dict()
+    # insert at the beginning of the list
+    if not _pre_commit_config_is_correct():
+        logger.info("Adding winipedia-utils hook to pre-commit config")
+        config["repos"] = [package_hook_config, *config.get("repos", [])]
+        dump_pre_commit_config(config)

winipedia_utils/git/pre_commit/hooks.py

@@ -0,0 +1,109 @@
+"""module contains functions that return the input for subprocess.run().
+
+Each function is named after the hook it represents. The docstring of each function
+describes the hook it represents. The function returns a list of strings that
+represent the command to run. The first string is the command, and the following
+strings are the arguments to the command. These funcs will be called by
+run_hooks.py, which will pass the returned list to subprocess.run().
+"""
+
+from pathlib import Path
+
+from winipedia_utils.projects.poetry.poetry import (
+    POETRY_PATH,
+    POETRY_RUN_ARGS,
+    POETRY_RUN_PYTHON_ARGS,
+    POETRY_RUN_RUFF_ARGS,
+)
+
+
+def _update_package_manager() -> list[str | Path]:
+    """Update the package manager.
+
+    This function returns the input for subprocess.run() to update the package
+    manager.
+    """
+    return [POETRY_PATH, "self", "update"]
+
+
+def _install_packages() -> list[str | Path]:
+    """Install all dependencies.
+
+    This function returns the input for subprocess.run() to install all dependencies.
+    """
+    return [POETRY_PATH, "install"]
+
+
+def _update_packages() -> list[str | Path]:
+    """Update all dependencies.
+
+    This function returns the input for subprocess.run() to update all dependencies.
+    """
+    return [POETRY_PATH, "update"]
+
+
+def _lock_dependencies() -> list[str | Path]:
+    """Lock the dependencies.
+
+    This function returns the input for subprocess.run() to lock the dependencies.
+    """
+    return [POETRY_PATH, "lock"]
+
+
+def _check_configurations() -> list[str | Path]:
+    """Check that poetry.lock and pyproject.toml is up to date.
+
+    This function returns the input for subprocess.run() to check that poetry.lock
+    is up to date.
+    """
+    return [POETRY_PATH, "check", "--strict"]
+
+
+def _creating_tests() -> list[str | Path]:
+    """Create all tests for the project.
+
+    This function returns the input for subprocess.run() to create all tests.
+    """
+    return [*POETRY_RUN_PYTHON_ARGS, "-m", "winipedia_utils.testing.create_tests"]
+
+
+def _linting() -> list[str | Path]:
+    """Check the code.
+
+    This function returns the input for subprocess.run() to lint the code.
+    It autofixes all errors that can be autofixed with --fix.
+    """
+    return [*POETRY_RUN_RUFF_ARGS, "check", "--fix"]
+
+
+def _formating() -> list[str | Path]:
+    """Format the code.
+
+    This function calls ruff format to format the code.
+    """
+    return [*POETRY_RUN_RUFF_ARGS, "format"]
+
+
+def _type_checking() -> list[str | Path]:
+    """Check the types.
+
+    This function returns the input for subprocess.run() to check the static types.
+    """
+    return [*POETRY_RUN_ARGS, "mypy"]
+
+
+def _security_checking() -> list[str | Path]:
+    """Check the security of the code.
+
+    This function returns the input for subprocess.run() to check the security of
+    the code.
+    """
+    return [*POETRY_RUN_ARGS, "bandit", "-c", "pyproject.toml", "-r", "."]
+
+
+def _testing() -> list[str | Path]:
+    """Run the tests.
+
+    This function returns the input for subprocess.run() to run all tests.
+    """
+    return [*POETRY_RUN_ARGS, "pytest"]

winipedia_utils/git/pre_commit/run_hooks.py

@@ -0,0 +1,49 @@
+"""Contains the pre-commit to run all hooks required by the winipedia_utils package.
+
+This script is meant to be run by pre-commit (https://pre-commit.com/)
+and should not be modified manually.
+"""
+
+import sys
+
+from winipedia_utils.git.pre_commit import hooks
+from winipedia_utils.logging.ansi import GREEN, RED, RESET
+from winipedia_utils.logging.logger import get_logger
+from winipedia_utils.modules.function import get_all_functions_from_module
+from winipedia_utils.os.os import run_subprocess
+
+logger = get_logger(__name__)
+
+
+def _run_all_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(
+            subprocess_args, check=False, capture_output=True, text=True
+        )
+        passed = result.returncode == 0
+
+        log_method = logger.info
+        passed_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
+        # 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,
+        )
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    _run_all_hooks()

winipedia_utils/iterating/__init__.py

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

winipedia_utils/iterating/iterate.py

@@ -0,0 +1,29 @@
+"""Iterating utilities for handling iterables.
+
+This module provides utility functions for working with iterables,
+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 typing import Any
+
+
+def get_len_with_default(iterable: Iterable[Any], default: int | None = None) -> int:
+    """Get the length of an iterable with a default value.
+
+    Args:
+        iterable: Iterable to get the length of
+        default: Default value to return if the iterable is empty
+
+    Returns:
+        Length of the iterable or the default value if the iterable is empty
+
+    """
+    try:
+        return len(iterable)  # type: ignore[arg-type]
+    except TypeError as e:
+        if default is None:
+            msg = "Can't get length of iterable and no default value provided"
+            raise TypeError(msg) from e
+        return default

winipedia_utils/logging/__init__.py

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

winipedia_utils/logging/ansi.py

@@ -0,0 +1,6 @@
+"""ANSI escape codes for terminal output."""
+
+RESET = "\033[0m"
+
+RED = "\033[91m"
+GREEN = "\033[92m"

winipedia_utils/logging/config.py

@@ -0,0 +1,64 @@
+"""Logging configuration for winipedia_utils.
+
+This module provides a standardized logging configuration dictionary that can be
+used with Python's logging.config.dictConfig() to set up consistent logging
+across the application. The configuration includes formatters, handlers, and
+logger settings for different components.
+"""
+
+# This dictionary can be passed directly to logging.config.dictConfig().
+# It sets up a single console handler that prints **all** log levels
+# (DEBUG, INFO, WARNING, ERROR and CRITICAL) using one consistent format.
+
+from typing import Any
+
+LOGGING_CONFIG: dict[str, Any] = {
+    "version": 1,  # Mandatory schema version for dictConfig
+    "disable_existing_loggers": False,  # Keep any loggers already created elsewhere
+    # ---------------------------- #
+    #  Define a single formatter   #
+    # ---------------------------- #
+    "formatters": {
+        "standard": {  # You can reference this formatter by name
+            "format": (
+                "%(asctime)s | "  # • %(asctime)s human-readable timestamp
+                "%(levelname)-8s | "  # • %(asctime)s human-readable timestamp
+                "%(filename)s:"  # • %(filename)s source file where the call was made
+                "%(lineno)d | "  # • %(lineno)d line number in that file
+                "%(message)s"  # • %(message)s the log message itself
+            ),
+            "datefmt": "%Y-%m-%d %H:%M:%S",  # Override default timestamp style
+        },
+    },
+    # --------------------------- #
+    #  Define the console output  #
+    # --------------------------- #
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",  # Send logs to sys.stderr
+            "level": "DEBUG",  # Capture *everything* ≥ DEBUG
+            "formatter": "standard",  # Use the formatter above
+            "stream": "ext://sys.stdout",  # Emit to stdout instead of stderr
+        },
+    },
+    # ------------------------------------------------------- #
+    #  Attach the handler to either the root logger or named  #
+    #  loggers. Below we set up the root so every message in  #
+    #  your application uses this setup automatically.        #
+    # ------------------------------------------------------- #
+    "root": {
+        "level": "DEBUG",  # Accept all levels from DEBUG upward
+        "handlers": ["console"],  # Pipe them through the console handler
+    },
+    # ------------------------------------------------------- #
+    #  Optionally, tweak individual libraries if they are     #
+    #  too noisy. For example, silence urllib3 INFO chatter.   #
+    # ------------------------------------------------------- #
+    "loggers": {
+        "urllib3": {
+            "level": "WARNING",  # Raise urllib3's threshold to WARNING
+            "handlers": ["console"],
+            "propagate": False,  # Prevent double-logging to the root
+        },
+    },
+}

winipedia_utils/logging/logger.py

@@ -0,0 +1,26 @@
+"""Logger utilities for winipedia_utils.
+
+This module provides functions for creating and configuring loggers
+throughout the application. It applies the standardized logging configuration
+defined in the config module to ensure consistent logging behavior.
+"""
+
+import logging
+from logging.config import dictConfig
+
+from winipedia_utils.logging.config import LOGGING_CONFIG
+
+dictConfig(LOGGING_CONFIG)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the given name.
+
+    Args:
+        name: The name for the logger, typically __name__ from the calling module
+
+    Returns:
+        A configured logger instance with the specified name
+
+    """
+    return logging.getLogger(name)

winipedia_utils/modules/__init__.py

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

winipedia_utils/modules/class_.py

@@ -0,0 +1,76 @@
+"""Class utilities for introspection and manipulation.
+
+This module provides utility functions for working with Python classes,
+including extracting methods from classes and finding classes within modules.
+These utilities are particularly useful for reflection, testing,
+and dynamic code generation.
+"""
+
+import inspect
+from collections.abc import Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+from winipedia_utils.modules.function import is_func
+
+
+def get_all_methods_from_cls(
+    class_: type, *, exclude_parent_methods: bool = False
+) -> list[Callable[..., Any]]:
+    """Get all methods from a class.
+
+    Retrieves all methods (functions or methods) from a class. Can optionally
+    exclude methods inherited from parent classes.
+
+    Args:
+        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
+    Returns:
+        A list of callable methods from the class
+
+    """
+    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+
+    methods = [
+        (method, name) for name, method in inspect.getmembers(class_) if is_func(method)
+    ]
+
+    if exclude_parent_methods:
+        methods = [
+            (method, name)
+            for method, name in methods
+            if get_module_of_obj(method).__name__ == class_.__module__
+            and name in class_.__dict__
+        ]
+
+    only_methods = [method for method, _name in methods]
+    # sort by definition order
+    return sorted(only_methods, key=get_def_line)
+
+
+def get_all_cls_from_module(module: ModuleType | str) -> list[type]:
+    """Get all classes defined in a module.
+
+    Retrieves all class objects that are defined directly in the specified module,
+    excluding imported classes.
+
+    Args:
+        module: The module to extract classes from
+
+    Returns:
+        A list of class types defined in the module
+
+    """
+    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+
+    if isinstance(module, str):
+        module = import_module(module)
+    classes = [
+        obj
+        for _, obj in inspect.getmembers(module, inspect.isclass)
+        if get_module_of_obj(obj).__name__ == module.__name__
+    ]
+    # sort by definition order
+    return sorted(classes, key=get_def_line)

winipedia_utils/modules/function.py

@@ -0,0 +1,86 @@
+"""Function utilities for introspection and manipulation.
+
+This module provides utility functions for working with Python functions,
+including extracting functions from modules and manipulating function objects.
+These utilities are particularly useful for reflection, testing, and
+dynamic code generation.
+"""
+
+import inspect
+from collections.abc import Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+
+def is_func_or_method(obj: Any) -> bool:
+    """Return True if *obj* is a function or method.
+
+    This function checks if the given object is a function or method,
+    including those defined in a class body.
+
+    Args:
+        obj: The object to check
+
+    Returns:
+        bool: True if the object is a function or method, False otherwise
+
+    """
+    return inspect.isfunction(obj) or inspect.ismethod(obj)
+
+
+def is_func(obj: Any) -> bool:
+    """Return True if *obj* is a 'method-like' attribute as it appears in a class body.
+
+    Accepts:
+
+
+        • plain functions (instance methods)
+        • staticmethod / classmethod descriptors
+        • property descriptors (getter counts as method)
+        • decorated functions that keep a __wrapped__ chain
+
+    Returns:
+        bool: True if the object is a method-like attribute, False otherwise
+
+    """
+    # plain function
+
+    if is_func_or_method(obj):
+        return True
+
+    if isinstance(obj, (staticmethod, classmethod, property)):
+        return True
+
+    # unwrap any wrappers (@functools.wraps) and retest
+
+    unwrapped = inspect.unwrap(obj)
+
+    return is_func_or_method(unwrapped)
+
+
+def get_all_functions_from_module(module: ModuleType | str) -> list[Callable[..., Any]]:
+    """Get all functions defined in a module.
+
+    Retrieves all function objects that are defined directly in the specified module,
+    excluding imported functions.
+    The functions are sorted by their line number in the module.
+
+    Args:
+        module: The module to extract functions from
+
+    Returns:
+        A list of callable functions defined in the module
+
+    """
+    from winipedia_utils.modules.module import get_def_line, get_module_of_obj
+
+    if isinstance(module, str):
+        module = import_module(module)
+    funcs = [
+        func
+        for _name, func in inspect.getmembers(module, is_func)
+        if get_module_of_obj(func).__name__ == module.__name__
+    ]
+    # sort by definition order
+    return sorted(funcs, key=get_def_line)