pyrig 2.2.6__py3-none-any.whl

pyrig/dev/utils/cli.py

@@ -0,0 +1,17 @@
+"""CLI utilities."""
+
+import sys
+from pathlib import Path
+
+from pyrig.src.modules.package import get_pkg_name_from_project_name
+
+
+def get_project_name_from_argv() -> str:
+    """Get the project name."""
+    return Path(sys.argv[0]).name
+
+
+def get_pkg_name_from_argv() -> str:
+    """Get the project and package name."""
+    project_name = get_project_name_from_argv()
+    return get_pkg_name_from_project_name(project_name)

pyrig/dev/utils/git.py

@@ -0,0 +1,312 @@
+"""GitHub repository API utilities and ruleset management.
+
+This module provides low-level utilities for interacting with the GitHub API,
+specifically for repository rulesets. It uses the PyGithub library for
+authentication and API calls.
+
+Rulesets are GitHub's newer mechanism for branch protection, offering more
+flexibility than the older branch protection rules. This module provides
+functions to create, update, and query rulesets.
+
+Attributes:
+    DEFAULT_BRANCH: The default branch name used by pyrig ("main").
+    DEFAULT_RULESET_NAME: The name of the default protection ruleset.
+
+Example:
+    >>> from pyrig.src.git.github.repo.repo import get_repo, create_or_update_ruleset
+    >>> repo = get_repo(token, "owner", "repo_name")
+    >>> rules = get_rules_payload(pull_request={"required_approving_review_count": 1})
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+from dotenv import dotenv_values
+from github import Github
+from github.Auth import Token
+from github.Repository import Repository
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BRANCH = "main"
+
+DEFAULT_RULESET_NAME = f"{DEFAULT_BRANCH} protection"
+
+
+def get_rules_payload(  # noqa: PLR0913
+    *,
+    creation: dict[str, Any] | None = None,
+    update: dict[str, Any] | None = None,
+    deletion: dict[str, Any] | None = None,
+    required_linear_history: dict[str, Any] | None = None,
+    merge_queue: dict[str, Any] | None = None,
+    required_deployments: dict[str, Any] | None = None,
+    required_signatures: dict[str, Any] | None = None,
+    pull_request: dict[str, Any] | None = None,
+    required_status_checks: dict[str, Any] | None = None,
+    non_fast_forward: dict[str, Any] | None = None,
+    commit_message_pattern: dict[str, Any] | None = None,
+    commit_author_email_pattern: dict[str, Any] | None = None,
+    committer_email_pattern: dict[str, Any] | None = None,
+    branch_name_pattern: dict[str, Any] | None = None,
+    tag_name_pattern: dict[str, Any] | None = None,
+    file_path_restriction: dict[str, Any] | None = None,
+    max_file_path_length: dict[str, Any] | None = None,
+    file_extension_restriction: dict[str, Any] | None = None,
+    max_file_size: dict[str, Any] | None = None,
+    workflows: dict[str, Any] | None = None,
+    code_scanning: dict[str, Any] | None = None,
+    copilot_code_review: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    """Build a rules array for a GitHub ruleset.
+
+    Args:
+        creation: Only allow users with bypass permission to create matching
+            refs.
+        update: Only allow users with bypass permission to update matching
+            refs.
+        deletion: Only allow users with bypass permissions to delete matching
+            refs.
+        required_linear_history: Prevent merge commits from being pushed to
+            matching refs.
+        merge_queue: Merges must be performed via a merge queue.
+        required_deployments: Choose which environments must be successfully
+            deployed to before refs can be pushed.
+        required_signatures: Commits pushed to matching refs must have verified
+            signatures.
+        pull_request: Require all commits be made to a non-target branch and
+            submitted via a pull request.
+        required_status_checks: Choose which status checks must pass before the
+            ref is updated.
+        non_fast_forward: Prevent users with push access from force pushing to
+            refs.
+        commit_message_pattern: Parameters to be used for the
+            commit_message_pattern rule.
+        commit_author_email_pattern: Parameters to be used for the
+            commit_author_email_pattern rule.
+        committer_email_pattern: Parameters to be used for the
+            committer_email_pattern rule.
+        branch_name_pattern: Parameters to be used for the branch_name_pattern
+            rule.
+        tag_name_pattern: Parameters to be used for the tag_name_pattern rule.
+        file_path_restriction: Prevent commits that include changes in
+            specified file and folder paths.
+        max_file_path_length: Prevent commits that include file paths that
+            exceed the specified character limit.
+        file_extension_restriction: Prevent commits that include files with
+            specified file extensions.
+        max_file_size: Prevent commits with individual files that exceed the
+            specified limit.
+        workflows: Require all changes made to a targeted branch to pass the
+            specified workflows.
+        code_scanning: Choose which tools must provide code scanning results
+            before the reference is updated.
+        copilot_code_review: Request Copilot code review for new pull requests
+            automatically.
+
+    Returns:
+        A list of rule objects to be used in a GitHub ruleset.
+    """
+    rules: list[dict[str, Any]] = []
+
+    rule_map = {
+        "creation": creation,
+        "update": update,
+        "deletion": deletion,
+        "required_linear_history": required_linear_history,
+        "merge_queue": merge_queue,
+        "required_deployments": required_deployments,
+        "required_signatures": required_signatures,
+        "pull_request": pull_request,
+        "required_status_checks": required_status_checks,
+        "non_fast_forward": non_fast_forward,
+        "commit_message_pattern": commit_message_pattern,
+        "commit_author_email_pattern": commit_author_email_pattern,
+        "committer_email_pattern": committer_email_pattern,
+        "branch_name_pattern": branch_name_pattern,
+        "tag_name_pattern": tag_name_pattern,
+        "file_path_restriction": file_path_restriction,
+        "max_file_path_length": max_file_path_length,
+        "file_extension_restriction": file_extension_restriction,
+        "max_file_size": max_file_size,
+        "workflows": workflows,
+        "code_scanning": code_scanning,
+        "copilot_code_review": copilot_code_review,
+    }
+
+    for rule_type, rule_config in rule_map.items():
+        if rule_config is not None:
+            rule_obj: dict[str, Any] = {"type": rule_type}
+            if rule_config:  # If there are parameters
+                rule_obj["parameters"] = rule_config
+            rules.append(rule_obj)
+
+    return rules
+
+
+def create_or_update_ruleset(  # noqa: PLR0913
+    token: str,
+    owner: str,
+    repo_name: str,
+    *,
+    ruleset_name: str,
+    enforcement: Literal["active", "disabled", "evaluate"] = "active",
+    target: Literal["branch", "tag", "push"] = "branch",
+    bypass_actors: list[dict[str, Any]] | None = None,
+    conditions: dict[
+        Literal["ref_name"], dict[Literal["include", "exclude"], list[str]]
+    ]
+    | None = None,
+    rules: list[dict[str, Any]] | None = None,
+) -> Any:
+    """Create or update a repository ruleset.
+
+    If a ruleset with the given name exists, it is updated. Otherwise,
+    a new ruleset is created.
+
+    Args:
+        token: GitHub API token with repo permissions.
+        owner: Repository owner (user or organization).
+        repo_name: Repository name.
+        ruleset_name: Name for the ruleset.
+        enforcement: Enforcement level ("active", "disabled", or "evaluate").
+        target: What the ruleset applies to ("branch", "tag", or "push").
+        bypass_actors: List of actors who can bypass the ruleset.
+        conditions: Branch/tag name patterns to include or exclude.
+        rules: List of rule objects from `get_rules_payload()`.
+
+    Returns:
+        The API response containing the created/updated ruleset.
+    """
+    repo = get_repo(token, owner, repo_name)
+    ruleset_id = ruleset_exists(
+        token=token, owner=owner, repo_name=repo_name, ruleset_name=ruleset_name
+    )
+    method = "PUT" if ruleset_id else "POST"
+    url = f"{repo.url}/rulesets"
+
+    if ruleset_id:
+        url += f"/{ruleset_id}"
+
+    payload: dict[str, Any] = {
+        "name": ruleset_name,
+        "enforcement": enforcement,
+        "target": target,
+        "conditions": conditions,
+        "rules": rules,
+    }
+    if bypass_actors:
+        payload["bypass_actors"] = bypass_actors
+
+    _headers, res = repo._requester.requestJsonAndCheck(  # noqa: SLF001
+        method,
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+        input=payload,
+    )
+
+    return res
+
+
+def get_all_rulesets(token: str, owner: str, repo_name: str) -> Any:
+    """Retrieve all rulesets defined for a repository.
+
+    Args:
+        token: GitHub API token.
+        owner: Repository owner.
+        repo_name: Repository name.
+
+    Returns:
+        A list of ruleset objects from the GitHub API.
+    """
+    repo = get_repo(token, owner, repo_name)
+    url = f"{repo.url}/rulesets"
+    method = "GET"
+    _headers, res = repo._requester.requestJsonAndCheck(  # noqa: SLF001
+        method,
+        url,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    return res
+
+
+def get_repo(token: str, owner: str, repo_name: str) -> Repository:
+    """Get a PyGithub Repository object for API operations.
+
+    Args:
+        token: GitHub API token.
+        owner: Repository owner (user or organization).
+        repo_name: Repository name.
+
+    Returns:
+        A PyGithub Repository object.
+    """
+    auth = Token(token)
+    github = Github(auth=auth)
+    return github.get_repo(f"{owner}/{repo_name}")
+
+
+def ruleset_exists(token: str, owner: str, repo_name: str, ruleset_name: str) -> int:
+    """Check if a ruleset with the given name exists.
+
+    Args:
+        token: GitHub API token.
+        owner: Repository owner.
+        repo_name: Repository name.
+        ruleset_name: Name of the ruleset to check for.
+
+    Returns:
+        The ruleset ID if it exists, 0 otherwise.
+    """
+    rulesets = get_all_rulesets(token, owner, repo_name)
+    main_ruleset = next((rs for rs in rulesets if rs["name"] == ruleset_name), None)
+    return main_ruleset["id"] if main_ruleset else 0
+
+
+def get_github_repo_token() -> str:
+    """Retrieve the GitHub repository token for API authentication.
+
+    Attempts to find a GitHub token in the following order:
+    1. The `REPO_TOKEN` environment variable
+    2. The `REPO_TOKEN` key in the project's `.env` file
+
+    This priority order ensures CI/CD environments (which typically set
+    environment variables) work seamlessly while allowing local development
+    to use .env files.
+
+    Returns:
+        The GitHub token string.
+
+    Raises:
+        ValueError: If no token is found in either location, or if the
+            .env file doesn't exist when falling back to it.
+
+    Note:
+        The token should have appropriate permissions for the intended
+        operations (e.g., repo scope for branch protection rules).
+    """
+    # try os env first
+    token = os.getenv("REPO_TOKEN")
+    if token:
+        return token
+
+    # try .env next
+    dotenv_path = Path(".env")
+    if not dotenv_path.exists():
+        msg = f"Expected {dotenv_path} to exist"
+        raise ValueError(msg)
+    dotenv = dotenv_values(dotenv_path)
+    token = dotenv.get("REPO_TOKEN")
+    if token:
+        return token
+
+    msg = f"Expected REPO_TOKEN in {dotenv_path}"
+    raise ValueError(msg)

pyrig/dev/utils/packages.py

@@ -0,0 +1,93 @@
+"""Helper functions for working with Python packages."""
+
+from collections.abc import 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 pyrig.src.modules.module import to_path
+from pyrig.src.modules.package import DOCS_DIR_NAME
+from pyrig.src.testing.convention import TESTS_PACKAGE_NAME
+
+
+def find_packages(
+    *,
+    depth: int | None = None,
+    include_namespace_packages: bool = False,
+    where: str = ".",
+    exclude: Iterable[str] | None = None,
+    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"]
+
+    """
+    gitignore_path = Path(".gitignore")
+    if exclude is None:
+        exclude = (
+            gitignore_path.read_text(encoding="utf-8").splitlines()
+            if gitignore_path.exists()
+            else []
+        )
+        exclude = [
+            p.replace("/", ".").removesuffix(".") for p in exclude if p.endswith("/")
+        ]
+    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 get_src_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
+
+    """
+    package_names = find_packages(depth=0, include_namespace_packages=False)
+    package_paths = [to_path(p, is_package=True) for p in package_names]
+    pkg = next(
+        p for p in package_paths if p.name not in {TESTS_PACKAGE_NAME, DOCS_DIR_NAME}
+    )
+    pkg_name = pkg.name
+
+    return import_module(pkg_name)

pyrig/dev/utils/resources.py

@@ -0,0 +1,77 @@
+"""Decorators for various purposes.
+
+This module provides decorators for various purposes, including:
+    - Retry and Exponential Handling
+"""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, ParamSpec
+
+from requests import RequestException
+from tenacity import retry, retry_if_exception_type, stop_after_attempt
+
+import pyrig
+from pyrig import resources
+from pyrig.src.git.git import git_add_file
+from pyrig.src.modules.package import get_pkg_name_from_cwd
+from pyrig.src.resource import get_resource_path
+
+P = ParamSpec("P")
+
+
+def return_resource_file_content_on_exceptions(
+    resource_name: str,
+    exceptions: tuple[type[Exception], ...],
+    *,
+    overwrite_resource: bool = True,
+    **tenacity_kwargs: Any,
+) -> Callable[[Callable[P, str]], Callable[P, str]]:
+    """Return content of a resource file if func raises specific exceptions.
+
+    post_process: Optional function that takes the result and returns a new value.
+    overwrite_resource: If True, write the result to the resource file.
+    """
+    resource_path = get_resource_path(resource_name, resources)
+    content = resource_path.read_text(encoding="utf-8").strip()
+
+    def decorator(func: Callable[P, str]) -> Callable[P, str]:
+        tenacity_decorator = retry(
+            retry=retry_if_exception_type(exception_types=exceptions),
+            stop=stop_after_attempt(
+                max_attempt_number=1
+            ),  # no retries, just catch once
+            retry_error_callback=lambda _state: content,
+            reraise=False,
+            **tenacity_kwargs,
+        )
+
+        # Apply tenacity decorator to the function once
+        decorated_func = tenacity_decorator(func)
+
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> str:
+            result = decorated_func(*args, **kwargs).strip()
+            if (
+                get_pkg_name_from_cwd() == pyrig.__name__
+                and overwrite_resource
+                and result != content
+            ):
+                resource_path.write_text(result, encoding="utf-8")
+                git_add_file(resource_path)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def return_resource_content_on_fetch_error(
+    resource_name: str,
+) -> Callable[[Callable[P, str]], Callable[P, str]]:
+    """Return content of a resource file if func raises a requests.HTTPError."""
+    exceptions = (RequestException,)
+    return return_resource_file_content_on_exceptions(
+        resource_name,
+        exceptions,
+    )

pyrig/dev/utils/testing.py

@@ -0,0 +1,66 @@
+"""Testing decorators and pytest mark utilities.
+
+This module provides convenience decorators for defining pytest fixtures
+with specific scopes and skip conditions. It simplifies common patterns
+like creating autouse fixtures or skipping tests in CI environments.
+
+Example:
+    Using a scoped fixture decorator::
+
+        @session_fixture
+        def database_connection():
+            return create_connection()
+
+    Using an autouse fixture::
+
+        @autouse_module_fixture
+        def setup_logging():
+            configure_logging()
+"""
+
+import functools
+
+import pytest
+
+from pyrig.src.git.git import running_in_github_actions
+
+#: Skip marker for fixture tests that cannot be called directly.
+skip_fixture_test: pytest.MarkDecorator = functools.partial(
+    pytest.mark.skip,
+    reason="Fixtures are not testable bc they cannot be called directly.",
+)()
+
+#: Skip marker for tests that cannot run in GitHub Actions.
+skip_in_github_actions: pytest.MarkDecorator = functools.partial(
+    pytest.mark.skipif,
+    running_in_github_actions(),
+    reason="Test cannot run in GitHub action.",
+)()
+
+#: Decorator for function-scoped fixtures.
+function_fixture = functools.partial(pytest.fixture, scope="function")
+#: Decorator for class-scoped fixtures.
+class_fixture = functools.partial(pytest.fixture, scope="class")
+#: Decorator for module-scoped fixtures.
+module_fixture = functools.partial(pytest.fixture, scope="module")
+#: Decorator for package-scoped fixtures.
+package_fixture = functools.partial(pytest.fixture, scope="package")
+#: Decorator for session-scoped fixtures.
+session_fixture = functools.partial(pytest.fixture, scope="session")
+
+#: Decorator for autouse function-scoped fixtures.
+autouse_function_fixture = functools.partial(
+    pytest.fixture, scope="function", autouse=True
+)
+#: Decorator for autouse class-scoped fixtures.
+autouse_class_fixture = functools.partial(pytest.fixture, scope="class", autouse=True)
+#: Decorator for autouse module-scoped fixtures.
+autouse_module_fixture = functools.partial(pytest.fixture, scope="module", autouse=True)
+#: Decorator for autouse package-scoped fixtures.
+autouse_package_fixture = functools.partial(
+    pytest.fixture, scope="package", autouse=True
+)
+#: Decorator for autouse session-scoped fixtures.
+autouse_session_fixture = functools.partial(
+    pytest.fixture, scope="session", autouse=True
+)