pyrig 2.2.6__py3-none-any.whl

pyrig/src/resource.py

@@ -0,0 +1,58 @@
+"""Resource file access utilities for development and PyInstaller builds.
+
+This module provides utilities for accessing static resource files (images,
+configuration files, data files, etc.) in a way that works both during
+development and when the application is bundled with PyInstaller.
+
+When running from source, resources are accessed from the filesystem. When
+running from a PyInstaller bundle, resources are extracted from the frozen
+executable's temporary directory (MEIPASS). Using `importlib.resources`
+handles both cases transparently.
+
+Resources should be placed in `pkg/dev/artifacts/resources/` directories
+and accessed via the `get_resource_path` function.
+
+Example:
+    >>> import my_project.dev.artifacts.resources as resources
+    >>> from pyrig.src.resource import get_resource_path
+    >>> config_path = get_resource_path("config.json", resources)
+    >>> data = config_path.read_text()
+"""
+
+from importlib.resources import as_file, files
+from pathlib import Path
+from types import ModuleType
+
+
+def get_resource_path(name: str, package: ModuleType) -> Path:
+    """Get the filesystem path to a resource file.
+
+    Resolves the path to a resource file within a package, handling both
+    development (source) and production (PyInstaller bundle) environments.
+    Uses `importlib.resources` to ensure compatibility with frozen executables.
+
+    Args:
+        name: The filename of the resource including extension
+            (e.g., "icon.png", "config.json").
+        package: The package module containing the resource. This should be
+            the `resources` package itself, not a parent package.
+
+    Returns:
+        A Path object pointing to the resource file. In development, this
+        is the actual file path. In a PyInstaller bundle, this is a path
+        to the extracted file in the temporary directory.
+
+    Example:
+        >>> import my_app.dev.artifacts.resources as resources
+        >>> icon_path = get_resource_path("icon.png", resources)
+        >>> print(icon_path)
+        /path/to/my_app/dev/artifacts/resources/icon.png
+
+    Note:
+        The returned path is only valid within the context of the current
+        process. For PyInstaller bundles, the file is extracted to a
+        temporary directory that is cleaned up when the process exits.
+    """
+    resource_path = files(package) / name
+    with as_file(resource_path) as path:
+        return path

pyrig/src/string.py

@@ -0,0 +1,100 @@
+"""String manipulation and naming convention utilities.
+
+This module provides utility functions for string transformations commonly needed
+when working with Python naming conventions. It handles conversions between
+different case styles (snake_case, PascalCase, kebab-case) and creates
+human-readable names from Python objects.
+
+These utilities are particularly useful for:
+    - Generating CLI command names from function names
+    - Creating display names for classes and modules
+    - Parsing and transforming identifiers
+
+Example:
+    >>> from pyrig.src.string import split_on_uppercase, make_name_from_obj
+    >>> split_on_uppercase("MyClassName")
+    ['My', 'Class', 'Name']
+    >>> make_name_from_obj("my_function_name")
+    'My-Function-Name'
+"""
+
+import re
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+
+def split_on_uppercase(string: str) -> list[str]:
+    """Split a string at uppercase letter boundaries.
+
+    Useful for parsing PascalCase or camelCase identifiers into their
+    component words. Empty strings between consecutive uppercase letters
+    are filtered out.
+
+    Args:
+        string: The string to split, typically in PascalCase or camelCase.
+
+    Returns:
+        A list of substrings, each starting with an uppercase letter
+        (except possibly the first if the original string started lowercase).
+
+    Example:
+        >>> split_on_uppercase("HelloWorld")
+        ['Hello', 'World']
+        >>> split_on_uppercase("XMLParser")
+        ['X', 'M', 'L', 'Parser']
+        >>> split_on_uppercase("lowercase")
+        ['lowercase']
+    """
+    return [s for s in re.split(r"(?=[A-Z])", string) if s]
+
+
+def make_name_from_obj(
+    obj: ModuleType | Callable[..., Any] | type | str,
+    split_on: str = "_",
+    join_on: str = "-",
+    *,
+    capitalize: bool = True,
+) -> str:
+    """Create a human-readable name from a Python object or string.
+
+    Transforms Python identifiers (typically in snake_case) into formatted
+    display names. Commonly used to generate CLI command names, display
+    labels, or documentation titles from function/class/module names.
+
+    Args:
+        obj: The object to extract a name from. Can be a module, callable,
+            class, or string. For non-string objects, uses the last component
+            of `__name__` (e.g., "my_module" from "package.my_module").
+        split_on: Character(s) to split the name on. Defaults to underscore
+            for snake_case input.
+        join_on: Character(s) to join the parts with. Defaults to hyphen
+            for kebab-case output.
+        capitalize: Whether to capitalize each word. When True, produces
+            Title-Case output.
+
+    Returns:
+        A formatted string with parts split and rejoined according to the
+        specified separators.
+
+    Example:
+        >>> make_name_from_obj("my_function_name")
+        'My-Function-Name'
+        >>> make_name_from_obj("my_function", join_on=" ", capitalize=True)
+        'My Function'
+        >>> import os
+        >>> make_name_from_obj(os.path)
+        'Path'
+    """
+    if not isinstance(obj, str):
+        name = getattr(obj, "__name__", "")
+        if not name:
+            msg = f"Cannot extract name from {obj}"
+            raise ValueError(msg)
+        obj_name: str = name.split(".")[-1]
+    else:
+        obj_name = obj
+    parts = obj_name.split(split_on)
+    if capitalize:
+        parts = [part.capitalize() for part in parts]
+    return join_on.join(parts)

pyrig/src/testing/__init__.py

@@ -0,0 +1,6 @@
+"""Testing utilities and test generation infrastructure.
+
+This package provides utilities for test creation, validation, and
+conventions. It includes automatic test skeleton generation, assertion
+helpers, and utilities for mapping between source and test objects.
+"""

pyrig/src/testing/assertions.py

@@ -0,0 +1,66 @@
+"""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.
+"""
+
+from typing import Any
+
+from pyrig.src.modules.function import is_abstractmethod
+
+
+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
+
+
+def assert_with_info(expr: bool, expected: Any, actual: Any, msg: str = "") -> None:  # noqa: FBT001
+    """Assert that an expression is true with a custom error message.
+
+    wraps around assert with msg and adds the expected and actual values to the message.
+
+    Args:
+        expr: The expression to evaluate for truthiness
+        expected: The expected value
+        actual: The actual value
+        msg: The error message to display if the assertion fails
+
+    Raises:
+        AssertionError: If the expression evaluates to False
+
+    """
+    msg = f"""
+Expected: {expected}
+Actual: {actual}
+{msg}
+"""
+    assert_with_msg(expr, msg)
+
+
+def assert_isabstrct_method(method: Any) -> None:
+    """Assert that a method is an abstract method.
+
+    Args:
+        method: The method to check
+
+    Raises:
+        AssertionError: If the method is not an abstract method
+
+    """
+    assert_with_msg(
+        is_abstractmethod(method),
+        f"Expected {method} to be abstract method",
+    )

pyrig/src/testing/convention.py

@@ -0,0 +1,203 @@
+"""Test naming conventions and object mapping utilities.
+
+This module defines pyrig's test naming conventions and provides bidirectional
+mapping between source objects and their corresponding test objects. The
+conventions follow pytest standards:
+
+    - Test functions: ``test_<function_name>``
+    - Test classes: ``Test<ClassName>``
+    - Test modules: ``test_<module_name>.py``
+    - Test package: ``tests/``
+
+Key functions:
+    - ``make_test_obj_name``: Generate test name from source object
+    - ``make_test_obj_importpath_from_obj``: Generate test import path
+    - ``get_test_obj_from_obj``: Get test object for a source object
+    - ``get_obj_from_test_obj``: Get source object for a test object
+
+Attributes:
+    TEST_FUNCTION_PREFIX: Prefix for test functions ("test_").
+    TEST_CLASS_PREFIX: Prefix for test classes ("Test").
+    TEST_MODULE_PREFIX: Prefix for test modules ("test_").
+    TESTS_PACKAGE_NAME: Name of the tests package ("tests").
+"""
+
+from collections.abc import Callable, Iterable
+from types import ModuleType
+from typing import Any, overload
+
+from pyrig.src.modules.module import (
+    get_isolated_obj_name,
+    import_obj_from_importpath,
+    make_obj_importpath,
+)
+
+COVERAGE_THRESHOLD = 90
+
+TEST_FUNCTION_PREFIX = "test_"
+
+TEST_CLASS_PREFIX = "Test"
+
+TEST_MODULE_PREFIX = TEST_FUNCTION_PREFIX
+
+TEST_PREFIXES = [TEST_FUNCTION_PREFIX, TEST_CLASS_PREFIX, TEST_MODULE_PREFIX]
+
+TESTS_PACKAGE_NAME = "tests"
+
+
+def get_right_test_prefix(obj: Callable[..., Any] | type | ModuleType) -> str:
+    """Get the appropriate test prefix for an object based on its type.
+
+    Args:
+        obj: The object to get the test prefix for (function, class, or module)
+
+    Returns:
+        The appropriate test prefix string for the given object type
+
+    """
+    if isinstance(obj, ModuleType):
+        return TEST_MODULE_PREFIX
+    if isinstance(obj, type):
+        return TEST_CLASS_PREFIX
+    return TEST_FUNCTION_PREFIX
+
+
+def make_test_obj_name(obj: Callable[..., Any] | type | ModuleType) -> str:
+    """Create a test name for an object by adding the appropriate prefix.
+
+    Args:
+        obj: The object to create a test name for
+
+    Returns:
+        The test name with the appropriate prefix
+
+    """
+    prefix = get_right_test_prefix(obj)
+    name = get_isolated_obj_name(obj)
+    return prefix + name
+
+
+def reverse_make_test_obj_name(test_name: str) -> str:
+    """Extract the original object name from a test name by removing the prefix.
+
+    Args:
+        test_name: The test name to extract the original name from
+
+    Returns:
+        The original object name without the test prefix
+
+    Raises:
+        ValueError: If the test name doesn't start with any of the expected prefixes
+
+    """
+    for prefix in TEST_PREFIXES:
+        if test_name.startswith(prefix):
+            return test_name.removeprefix(prefix)
+    msg = f"{test_name=} is expected to start with one of {TEST_PREFIXES=}"
+    raise ValueError(msg)
+
+
+def make_test_obj_importpath_from_obj(
+    obj: Callable[..., Any] | type | ModuleType,
+) -> str:
+    """Create an import path for a test object based on the original object.
+
+    Args:
+        obj: The original object to create a test import path for
+
+    Returns:
+        The import path for the corresponding test object
+
+    """
+    parts = make_obj_importpath(obj).split(".")
+    test_name = make_test_obj_name(obj)
+    test_parts = [
+        (TEST_MODULE_PREFIX if part[0].islower() else TEST_CLASS_PREFIX) + part
+        for part in parts
+    ]
+    test_parts[-1] = test_name
+    test_parts.insert(0, TESTS_PACKAGE_NAME)
+    return ".".join(test_parts)
+
+
+def make_obj_importpath_from_test_obj(
+    test_obj: Callable[..., Any] | type | ModuleType,
+) -> str:
+    """Create an import path for an original object based on its test object.
+
+    Args:
+        test_obj: The test object to create an original import path for
+
+    Returns:
+        The import path for the corresponding original object
+
+    """
+    test_parts = make_obj_importpath(test_obj).split(".")
+    test_parts = test_parts[1:]
+    parts = [reverse_make_test_obj_name(part) for part in test_parts]
+    return ".".join(parts)
+
+
+@overload
+def get_test_obj_from_obj(obj: type) -> type: ...
+
+
+@overload
+def get_test_obj_from_obj(obj: Callable[..., Any]) -> Callable[..., Any]: ...
+
+
+@overload
+def get_test_obj_from_obj(obj: ModuleType) -> ModuleType: ...
+
+
+def get_test_obj_from_obj(
+    obj: Callable[..., Any] | type | ModuleType,
+) -> Callable[..., Any] | type | ModuleType:
+    """Get the test object corresponding to an original object.
+
+    Args:
+        obj: The original object to get the test object for
+
+    Returns:
+        The corresponding test object
+
+    """
+    test_obj_path = make_test_obj_importpath_from_obj(obj)
+    return import_obj_from_importpath(test_obj_path)
+
+
+def get_obj_from_test_obj(
+    test_obj: Callable[..., Any] | type | ModuleType,
+) -> Callable[..., Any] | type | ModuleType:
+    """Get the original object corresponding to a test object.
+
+    Args:
+        test_obj: The test object to get the original object for
+
+    Returns:
+        The corresponding original object
+
+    """
+    obj_importpath = make_obj_importpath_from_test_obj(test_obj)
+    return import_obj_from_importpath(obj_importpath)
+
+
+def make_summary_error_msg(
+    errors_locations: Iterable[str],
+) -> str:
+    """Create an error message summarizing multiple error locations.
+
+    Args:
+        errors_locations: Collection of error locations
+
+    Returns:
+        A formatted error message listing all error locations
+    """
+    msg = """
+    Found errors at:
+    """
+    for error_location in errors_locations:
+        msg += f"""
+        - {error_location}
+        """
+    return msg

pyrig-2.2.6.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: pyrig
+Version: 2.2.6
+Summary: A Python toolkit that standardizes and automates project setup, configuration and development.
+Author: Winipedia
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typer>=0.20.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pyrig
+
+<!-- tooling -->
+[![pyrig](https://img.shields.io/badge/built%20with-pyrig-3776AB?logo=buildkite&logoColor=black)](https://github.com/Winipedia/pyrig)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Container](https://img.shields.io/badge/Container-Podman-A23CD6?logo=podman&logoColor=grey&colorA=0D1F3F&colorB=A23CD6)](https://podman.io/)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)
+<!-- code-quality -->
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)[![mypy](https://img.shields.io/badge/type%20checked-mypy-039dfc.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![pytest](https://img.shields.io/badge/tested%20with-pytest-46a2f1.svg?logo=pytest)](https://pytest.org/)
+[![codecov](https://codecov.io/gh/Winipedia/pyrig/branch/main/graph/badge.svg)](https://codecov.io/gh/Winipedia/pyrig)
+<!-- package-info -->
+[![PyPI](https://img.shields.io/pypi/v/pyrig?logo=pypi&logoColor=white)](https://pypi.org/project/pyrig/)
+[![Python](https://img.shields.io/badge/python-3.12|3.13|3.14-blue.svg?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/Winipedia/pyrig)](https://github.com/Winipedia/pyrig/blob/main/LICENSE)
+<!-- ci/cd -->
+[![CI](https://img.shields.io/github/actions/workflow/status/Winipedia/pyrig/health_check.yaml?label=CI&logo=github)](https://github.com/Winipedia/pyrig/actions/workflows/health_check.yaml)
+[![CD](https://img.shields.io/github/actions/workflow/status/Winipedia/pyrig/release.yaml?label=CD&logo=github)](https://github.com/Winipedia/pyrig/actions/workflows/release.yaml)
+
+---
+
+> A Python toolkit that standardizes and automates project setup, configuration and development.
+
+---
+
+## What is pyrig?
+
+**pyrig** is an opinionated Python project framework that enforces best practices and keeps your projects up-to-date automatically. Unlike traditional project templates, pyrig is a living system that manages your entire development lifecycle. Pyrig makes project development seemless and keeps you focused on your code. It allows even in bigger project to not lose the overview. It opinionated and best practices approach allows you to always know what belongs where and where to find things. 
+
+### Key Features
+
+- **Automated Setup** - Initialize production-ready projects in seconds with `pyrig init`
+- **Living Configuration** - Configs stay synchronized automatically, no manual maintenance
+- **Enforced Quality** - Strict linting, type checking, testing, and security scanning out of the box
+- **Always Current** - Automatic dependency updates and latest tool versions via CI/CD
+- **Multi-Package Support** - Build package ecosystems with cross-package discovery of ConfigFiles, Builders, fixtures, and CLI commands
+- **Extensible Architecture** - Plugin system for custom ConfigFiles and Builders
+
+### Philosophy
+
+pyrig is designed for **serious, long-term Python projects** where code quality and maintainability matter. It makes opinionated choices about tooling and enforces best practices, so you can focus on building features instead of configuring tools and wondering whta is the best way to do something.
+
+## Quick Start
+
+### Prerequisites
+
+- **Git** with username matching your GitHub username
+- **uv** package manager
+- **Podman** (for containerization)
+
+### Installation
+
+```bash
+# Create a new GitHub repository (don't initialize with README)
+# Clone it locally
+git clone https://github.com/YourUsername/your-project.git
+cd your-project
+
+# Initialize with uv
+uv init
+
+# Add pyrig
+uv add pyrig
+
+# Initialize your project (this does everything!)
+uv run pyrig init
+```
+
+That's it! You now have a fully configured project with:
+- Automated testing with pytest (90% coverage requirement)
+- Linting and formatting with ruff (ALL rules enabled)
+- Type checking with ty and mypy (strict mode)
+- Security scanning with bandit
+- Pre-commit hooks for quality enforcement
+- GitHub Actions CI/CD workflows
+- Branch protection and repository security
+- Containerfile for deployment
+- Custom CLI commands via `dev/cli/subcommands.py` and `dev/cli/shared_subcommands.py`
+
+### Next Steps
+
+After initialization, start coding in `<package>/src/` and run:
+
+```bash
+uv run pyrig mktests    # Generate test skeletons
+uv run pytest           # Run tests
+git add .
+git commit -m "Add feature"  # Pre-commit hooks run automatically
+git push
+```
+
+## Documentation
+
+- **[Documentation Index](docs/index.md)** - Full documentation
+- **[Getting Started Guide](docs/getting-started.md)** - Complete guide to creating your first pyrig project
+- **[Multi-Package Architecture](docs/multi-package-architecture.md)** - Build package ecosystems with cross-package discovery
+- **[Configuration Files Reference](docs/config-files/index.md)** - Detailed documentation for every config file
+
+## Technology Stack
+
+pyrig uses cutting-edge Python tooling:
+
+- **[uv](https://github.com/astral-sh/uv)** - Fast Python package manager
+- **[ruff](https://github.com/astral-sh/ruff)** - Extremely fast linter and formatter
+- **[ty](https://github.com/astral-sh/ty)** - Fast type checker
+- **[mypy](https://mypy-lang.org/)** - Static type checker
+- **[pytest](https://pytest.org/)** - Testing framework
+- **[bandit](https://github.com/PyCQA/bandit)** - Security scanner
+- **[pre-commit](https://pre-commit.com/)** - Git hook framework
+- **[Podman](https://podman.io/)** - Daemonless container runtime
+- **[GitHub Actions](https://github.com/features/actions)** - CI/CD platform
+
+## What Makes pyrig Different?
+
+Unlike cookiecutter, copier, or other project templates:
+
+- **Living** - Configs stay synchronized automatically, not just at creation time
+- **Opinionated** - Best practices enforced, not suggested
+- **Comprehensive** - Handles everything from init to deployment
+- **Current** - Automatically updates to latest tools and standards
+- **Extensible** - Plugin architecture for custom functionality
+
+## Project Structure
+
+pyrig creates a clean, organized structure:
+
+```
+your-project/
+├── <package>/
+│   ├── dev/        # Development tools (not in production)
+│   ├── src/        # Your application code
+│   └── resources/  # Static files
+├── tests/          # Test suite (mirrors src/)
+├── docs/           # Documentation
+├── .github/        # CI/CD workflows
+└── ...             # Config files
+```
+
+## Requirements
+
+- Git (any recent version)
+- uv package manager
+- GitHub account (for CI/CD and repository protection)
+- Podman (optional, for containerization)
+
+## Contributing
+
+Contributions are welcome! pyrig is built with pyrig itself, so you can explore the codebase to see how it works.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- **PyPI**: [pypi.org/project/pyrig](https://pypi.org/project/pyrig/)
+- **Documentation**: [docs/](docs/)
+- **Issues**: [github.com/Winipedia/pyrig/issues](https://github.com/Winipedia/pyrig/issues)
+- **Source**: [github.com/Winipedia/pyrig](https://github.com/Winipedia/pyrig)