winipedia-utils 0.3.43__tar.gz → 0.4.12__tar.gz

{winipedia_utils-0.3.43 → winipedia_utils-0.4.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: winipedia-utils
-Version: 0.3.43
+Version: 0.4.12
 Summary: A package with many utility functions
 License-Expression: MIT
 License-File: LICENSE
@@ -16,6 +16,7 @@ Requires-Dist: defusedxml
 Requires-Dist: keyring
 Requires-Dist: pathspec
 Requires-Dist: polars
+Requires-Dist: pygithub
 Requires-Dist: pyyaml
 Requires-Dist: setuptools
 Requires-Dist: tomlkit
@@ -62,13 +63,26 @@ A comprehensive Python utility package that enforces best practices, automates p
 
 ## Quick Start
 
-### Installation
+### How to setup a new project
 
 ```bash
-# Add winipedia-utils to your project
+# 1: Create a new repository on GitHub
+# The default branch must be called main
+# add a PAT or Fine-Grained Access Token to your repo secrets called REPO_TOKEN that has write access to the repository (needed for branch protection in health_check.yaml - see winipedia_utils.git.github.repo.protect)
+
+# 2: Clone the repository
+git clone https://github.com/owner/repo.git
+
+# 3: Create a new poetry project
+poetry init # or poetry new
+# 4: Poetry will ask you some stuff when you run poetry init.
+# First author name must be equal to the GitHub repository owner (username).
+# The repository name must be equal to the package/project name.
+
+# 5: Add winipedia-utils to your project
 poetry add winipedia-utils
 
-# Run the automated setup
+# 6: Run the automated setup
 poetry run python -m winipedia_utils.setup
 ```
 
@@ -88,8 +102,9 @@ The setup creates the following configuration files:
 - `.pre-commit-config.yaml` - Pre-commit hook configuration
 - `.gitignore` - Git ignore rules (assumes you added one on GitHub before.)
 - `pyproject.toml` - Project configuration with Poetry settings
-- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when oushing to main)
-- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow)
+- `.github/workflows/health_check.yaml` - Health check workflow (Runs on every push and pull request)
+- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when the same actions as in health check pass and commits are pushed to main)
+- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow, if you use this workflow, you need to add a PYPI_TOKEN (named PYPI_TOKEN) to your GitHub secrets that has write access to the package on PyPI.)
 - `py.typed` - PEP 561 marker for type hints
 - `experiment.py` - For experimentation (ignored by git)
 - `test0.py` - Test file with one empyt test (so that initial tests pass)
@@ -106,8 +121,8 @@ Usually VSCode or other IDEs activates the venv automatically when opening the t
 1. Patch version (poetry version patch)
 2. Add version patch to git (git add pyproject.toml)
 3. Update package manager (poetry self update)
-4. Install packages (poetry install)
-5. Update packages (poetry update)
+4. Install packages (poetry install --with dev)
+5. Update packages (poetry update --with dev (winipedia_utils forces all dependencies with * to be updated to latest compatible version))
 6. Lock dependencies (poetry lock)
 7. Check package manager configs (poetry check --strict)
 8. Create tests (python -m winipedia_utils.testing.create_tests)

{winipedia_utils-0.3.43 → winipedia_utils-0.4.12}/README.md

@@ -38,13 +38,26 @@ A comprehensive Python utility package that enforces best practices, automates p
 
 ## Quick Start
 
-### Installation
+### How to setup a new project
 
 ```bash
-# Add winipedia-utils to your project
+# 1: Create a new repository on GitHub
+# The default branch must be called main
+# add a PAT or Fine-Grained Access Token to your repo secrets called REPO_TOKEN that has write access to the repository (needed for branch protection in health_check.yaml - see winipedia_utils.git.github.repo.protect)
+
+# 2: Clone the repository
+git clone https://github.com/owner/repo.git
+
+# 3: Create a new poetry project
+poetry init # or poetry new
+# 4: Poetry will ask you some stuff when you run poetry init.
+# First author name must be equal to the GitHub repository owner (username).
+# The repository name must be equal to the package/project name.
+
+# 5: Add winipedia-utils to your project
 poetry add winipedia-utils
 
-# Run the automated setup
+# 6: Run the automated setup
 poetry run python -m winipedia_utils.setup
 ```
 
@@ -64,8 +77,9 @@ The setup creates the following configuration files:
 - `.pre-commit-config.yaml` - Pre-commit hook configuration
 - `.gitignore` - Git ignore rules (assumes you added one on GitHub before.)
 - `pyproject.toml` - Project configuration with Poetry settings
-- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when oushing to main)
-- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow)
+- `.github/workflows/health_check.yaml` - Health check workflow (Runs on every push and pull request)
+- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when the same actions as in health check pass and commits are pushed to main)
+- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow, if you use this workflow, you need to add a PYPI_TOKEN (named PYPI_TOKEN) to your GitHub secrets that has write access to the package on PyPI.)
 - `py.typed` - PEP 561 marker for type hints
 - `experiment.py` - For experimentation (ignored by git)
 - `test0.py` - Test file with one empyt test (so that initial tests pass)
@@ -82,8 +96,8 @@ Usually VSCode or other IDEs activates the venv automatically when opening the t
 1. Patch version (poetry version patch)
 2. Add version patch to git (git add pyproject.toml)
 3. Update package manager (poetry self update)
-4. Install packages (poetry install)
-5. Update packages (poetry update)
+4. Install packages (poetry install --with dev)
+5. Update packages (poetry update --with dev (winipedia_utils forces all dependencies with * to be updated to latest compatible version))
 6. Lock dependencies (poetry lock)
 7. Check package manager configs (poetry check --strict)
 8. Create tests (python -m winipedia_utils.testing.create_tests)

{winipedia_utils-0.3.43 → winipedia_utils-0.4.12}/pyproject.toml

@@ -1,7 +1,7 @@
 # Project section
 [project]
 name = "winipedia-utils"
-version = "0.3.43"
+version = "0.4.12"
 description = "A package with many utility functions"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,6 +30,7 @@ pyyaml = "*"
 keyring = "*"
 cryptography = "*"
 polars = "*"
+pygithub = "*"
 
 [tool.poetry.group.dev.dependencies]
 ruff = "*"

winipedia_utils-0.4.12/winipedia_utils/git/github/repo/protect.py

@@ -0,0 +1,104 @@
+"""Script to protect the repo and branches of a repository."""
+
+from typing import Any
+
+from winipedia_utils.git.github.repo.repo import (
+    DEFAULT_BRANCH,
+    DEFAULT_RULESET_NAME,
+    create_or_update_ruleset,
+    get_repo,
+    get_rules_payload,
+)
+from winipedia_utils.git.github.workflows.health_check import HealthCheckWorkflow
+from winipedia_utils.modules.package import get_src_package
+from winipedia_utils.projects.poetry.config import PyprojectConfigFile
+from winipedia_utils.testing.tests.base.utils.utils import get_github_repo_token
+
+
+def protect_repository() -> None:
+    """Protect the repository."""
+    set_secure_repo_settings()
+    create_or_update_default_branch_ruleset()
+
+
+def set_secure_repo_settings() -> None:
+    """Set standard settings for the repository."""
+    src_pkg_name = get_src_package().__name__
+    owner = PyprojectConfigFile.get_main_author_name()
+    token = get_github_repo_token()
+    repo = get_repo(token, owner, src_pkg_name)
+
+    toml_description = PyprojectConfigFile.load()["project"]["description"]
+
+    repo.edit(
+        name=src_pkg_name,
+        description=toml_description,
+        default_branch=DEFAULT_BRANCH,
+        delete_branch_on_merge=True,
+        allow_update_branch=True,
+        allow_merge_commit=False,
+        allow_rebase_merge=True,
+        allow_squash_merge=True,
+    )
+
+
+def create_or_update_default_branch_ruleset() -> None:
+    """Add a branch protection rule to the repository."""
+    create_or_update_ruleset(
+        **get_default_ruleset_params(),
+    )
+
+
+def get_default_ruleset_params() -> dict[str, Any]:
+    """Get the default ruleset parameters."""
+    src_pkg_name = get_src_package().__name__
+    token = get_github_repo_token()
+
+    rules = get_rules_payload(
+        deletion={},
+        non_fast_forward={},
+        creation={},
+        update={},
+        pull_request={
+            "required_approving_review_count": 1,
+            "dismiss_stale_reviews_on_push": True,
+            "require_code_owner_review": True,
+            "require_last_push_approval": True,
+            "required_review_thread_resolution": True,
+            "automatic_copilot_code_review_enabled": False,
+            "allowed_merge_methods": ["merge", "squash", "rebase"],
+        },
+        required_linear_history={},
+        required_signatures={},
+        required_status_checks={
+            "strict_required_status_checks_policy": True,
+            "do_not_enforce_on_create": False,
+            "required_status_checks": [
+                {
+                    "context": HealthCheckWorkflow.get_workflow_name(),
+                }
+            ],
+        },
+    )
+
+    return {
+        "owner": PyprojectConfigFile.get_main_author_name(),
+        "token": token,
+        "repo_name": src_pkg_name,
+        "ruleset_name": DEFAULT_RULESET_NAME,
+        "enforcement": "active",
+        "bypass_actors": [
+            {
+                "actor_id": 5,
+                "actor_type": "RepositoryRole",
+                "bypass_mode": "always",
+            }
+        ],
+        "target": "branch",
+        "conditions": {"ref_name": {"include": ["~DEFAULT_BRANCH"], "exclude": []}},
+        "rules": rules,
+    }
+
+
+if __name__ == "__main__":
+    protect_repository()

winipedia_utils-0.4.12/winipedia_utils/git/github/repo/repo.py

@@ -0,0 +1,205 @@
+"""Contains utilities for working with GitHub repositories."""
+
+from typing import Any, Literal
+
+from github import Github
+from github.Auth import Token
+from github.Repository import Repository
+
+from winipedia_utils.logging.logger import get_logger
+
+logger = get_logger(__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 a ruleset for the repository."""
+    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:
+    """Get all rulesets for the repository."""
+    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 the repository."""
+    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 the main protection ruleset exists."""
+    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