### Install and Configure Git

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/getting-started.md

Commands to verify Git installation, configure user name and email globally. This is a foundational step for version control.

```bash
git --version
git config --global user.name "YourGitHubUsername"
git config --global user.email "your.email@example.com"
```

--------------------------------

### Install Podman Containerization Tool

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/getting-started.md

Provides commands for installing Podman, a containerization tool, on Debian/Ubuntu, Fedora, and macOS. Includes verification of the installation.

```bash
# Linux
sudo apt install podman  # Debian/Ubuntu
sudo dnf install podman  # Fedora

# macOS
brew install podman

# Verify installation
podman --version
```

--------------------------------

### Create GitHub Repository

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/getting-started.md

Instructions for creating a new repository on GitHub. It specifies naming, description, visibility, and notes that pyrig will handle .gitignore and README initialization.

```bash
# On GitHub.com:
# 1. Click "New repository"
# 2. Name: my-project
# 3. Description: Your project description
# 4. Public or Private
# 5. You do not need to initialize with README, 
#   .gitignore bc pyrig will create it for you. 
#   (create a license if you do not want the MIT license)
# 6. Click "Create repository"
```

--------------------------------

### Clone GitHub Repository

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/getting-started.md

Clones a newly created GitHub repository and navigates into the project directory. Includes a verification step for the remote configuration.

```bash
# Clone the empty repository
git clone https://github.com/YourUsername/my-project.git
cd my-project

# Verify remote is set
git remote -v
```

--------------------------------

### Install and Verify uv Package Manager

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/getting-started.md

Installs the uv Python package manager using a script from astral.sh and verifies the installation. uv is essential for managing Python dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version
```

--------------------------------

### Setup uv Package Manager

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/workflows/release.md

Installs the uv package manager and pins a specific Python version (3.14) for the build environment.

```yaml
      - name: Setup Package Manager
        uses: astral-sh/setup-uv@main
        with:
          python-version: "3.14"
```

--------------------------------

### Prek CLI Commands for Installation and Execution

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/pre_commit.md

These bash commands demonstrate how to install and manually run Prek hooks. The `uv run pyrig init` command installs hooks, while `uv run prek install` performs a manual installation. Hooks can be run on all files or specific ones with optional verbose output.

```bash
uv run pyrig init

```

```bash
uv run prek install

```

```bash
uv run prek run --all-files

```

```bash
uv run prek run lint-code

```

```bash
uv run prek run --all-files --verbose

```

--------------------------------

### Run pyrig CLI Commands (Bash)

Source: https://github.com/winipedia/pyrig/blob/main/docs/cli/index.md

Examples of how to execute pyrig CLI commands using the 'uv run' command. This includes project setup, structure creation, building artifacts, and displaying the version. It also shows how to run commands for dependent applications.

```bash
uv run pyrig init        # Complete project setup
uv run pyrig mkroot      # Create project structure
uv run pyrig build       # Build all artifacts
uv run pyrig version     # Display version
```

```bash
uv run myapp <command>   # Run myapp-specific commands
uv run myapp version     # Shared commands work too
```

--------------------------------

### Custom Content Addition to MkDocs Index

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/index_md.md

This example shows how to add custom content to the `docs/index.md` file after the automatically generated header and badges. The validation ensures required elements are present, allowing for flexible additions like welcome messages, features, and getting started guides.

```markdown
# myapp Documentation

<!-- badges here -->

---

> A sample application

---

## Welcome

This is the documentation for myapp.

## Features

- Feature 1
- Feature 2

## Getting Started

...
```

--------------------------------

### Setup uv Package Manager

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/workflows/build.md

This action sets up the 'uv' package manager. It installs 'uv' using the default Python version supported by the environment. This is a prerequisite for managing project dependencies and versions.

```yaml
steps:
  - name: Setup Package Manager
    uses: astral-sh/setup-uv@main
```

--------------------------------

### Initialize pyrig Project using uv

Source: https://github.com/winipedia/pyrig/blob/main/README.md

This snippet demonstrates the initial setup of a project using the 'uv' package manager and the 'pyrig' toolkit. It involves initializing the environment, adding pyrig as a dependency, and then running the pyrig initialization command.

```bash
uv init
uv add pyrig
uv run pyrig init
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/workflows/health_check.md

Synchronizes and installs project dependencies based on the lock file using the uv package manager. This ensures that all necessary packages are installed in the correct versions, preparing the environment for subsequent build and test steps.

```bash
uv sync
```

--------------------------------

### Containerfile Layer Structure Example (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/container_file.md

Illustrates the discrete layers that constitute the generated Containerfile. Each string represents a Dockerfile instruction, defining the build process from base image to entrypoint.

```python
[
    "FROM python:3.12-slim",
    "WORKDIR /my-project",
    "COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv",
    "COPY README.md LICENSE pyproject.toml uv.lock ./",
    "RUN useradd -m -u 1000 appuser",
    "RUN chown -R appuser:appuser .",
    "USER appuser",
    "COPY --chown=appuser:appuser my_project my_project",
    "RUN uv sync --no-group dev",
    "RUN rm README.md LICENSE pyproject.toml uv.lock",
    'ENTRYPOINT ["uv", "run", "my-project"]',
    'CMD ["main"]'
]
```

--------------------------------

### Update and Install Dependencies with uv

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/workflows/release.md

Updates the project's lock file and installs all dependencies using the uv package manager.

```bash
      - name: Update Dependencies
        run: uv lock --upgrade

      - name: Install Dependencies
        run: uv sync
```

--------------------------------

### Google-Style Docstring Example (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/api_md.md

An example demonstrating the Google-style docstring format used by pyrig for Python functions. This format includes sections for arguments, return values, and raised exceptions, which are automatically parsed and formatted by mkdocstrings.

```python
def my_function(param1: str, param2: int) -> bool:
    """Short description of the function.

    Longer description with more details about what the
    function does and how to use it.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When param2 is negative.
    """
    if param2 < 0:
        raise ValueError("param2 must be non-negative")
    return len(param1) > param2
```

--------------------------------

### Discover Config Files (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

This Python script uses the 'pyrig' library to discover all subclasses of `ConfigFile`. It prints the total count and the module path for each discovered configuration file, useful for verifying setup.

```python
from pyrig.rig.configs.base.base import ConfigFile
configs = ConfigFile.subclasses()
print(f'Found {len(configs)} config files')
for c in configs:
    print(f'  - {c.__module__}.{c.__name__}')
```

--------------------------------

### Using PyRig Tool Wrappers (Python)

Source: https://context7.com/winipedia/pyrig/llms.txt

Demonstrates how to use pre-defined tool wrappers in PyRig for linting, testing, and package management. It shows how to get, inspect, modify, and execute command arguments for these tools.

```python
from pyrig.rig.tools.linter import Linter
from pyrig.rig.tools.project_tester import ProjectTester
from pyrig.rig.tools.package_manager import PackageManager

# Get command arguments
lint_args = Linter.I.check_args()
print(lint_args)  # ruff check

# Execute the command
lint_args.run()

# Run tests
test_args = ProjectTester.I.run_args()
print(test_args)  # pytest
test_args.run()

# Install dependencies
sync_args = PackageManager.I.install_dependencies_args()
print(sync_args)  # uv sync
sync_args.run()
```

--------------------------------

### Bash command to initialize pyrig project

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/main.md

This bash command is used to initialize a pyrig project, which also triggers the creation of the main.py file. It's an alternative to 'uv run pyrig mkroot' for project setup.

```bash
uv run pyrig init

```

--------------------------------

### Keywords for PyPI Discoverability

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/pyproject.md

Provides examples of how to define keywords in pyproject.toml to improve project discoverability on PyPI. Keywords should be relevant search terms, ideally 5-8 in number, and mix broad and specific terms.

```toml
keywords = ["web-framework", "async", "api", "rest", "microservices"]

```

```toml
keywords = ["cli", "automation", "task-runner", "productivity", "devops"]

```

```toml
keywords = ["data-processing", "etl", "pipeline", "analytics", "big-data"]

```

--------------------------------

### Add New TOML Configuration File (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/architecture.md

Demonstrates how to create a new TOML configuration file by subclassing TomlConfigFile. This example defines a custom configuration for 'app' and specifies its location. This file is automatically discovered by pyrig.

```python
# myapp/rig/configs/my_config.py
from pathlib import Path
from pyrig.rig.configs.base.toml import TomlConfigFile

class MyAppConfigFile(TomlConfigFile):

    def parent_path(self) -> Path:
        return Path()


    def _configs(self) -> dict:
        return {"app": {"name": "myapp"}}

```

--------------------------------

### Initialize Microservice with PyRig and Service Base

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

Demonstrates the command-line steps to create a new microservice, clone its repository, and initialize it using PyRig. It includes adding the 'service-base' dependency and running the PyRig initialization command.

```bash
# Create repository
gh repo create myorg/auth-service
git clone https://github.com/myorg/auth-service.git
cd auth-service

# Initialize with pyrig
uv init
# service base brings pyrig bc it is build with it
uv add service-base
uv run pyrig init

```

--------------------------------

### Initialize New Services with PyRig

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

Commands to initialize new services like `payment-service` and `notification-service`. It involves creating a new directory, adding the `service-base` dependency, and then running `pyrig init`.

```bash
# Payment service
uv init && uv add service-base && uv run pyrig init

# Notification service
uv init && uv add service-base && uv run pyrig init
```

--------------------------------

### Initialize New Microservice (Bash)

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

This command initializes a new microservice, adds the 'service-base' dependency, and runs 'pyrig init'. It's a quick way to create a production-ready service adhering to all shared standards.

```bash
uv init && uv add service-base && uv run pyrig init
```

--------------------------------

### Initialize pyrig Project with uv

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

Initializes a new project using uv and adds pyrig as a dependency. This sets up the foundational structure for a pyrig-managed project.

```bash
# Create repository
gh repo create myorg/service-base --public  # Or private if you want
git clone https://github.com/myorg/service-base.git
cd service-base

# Initialize with pyrig
uv init
uv add pyrig
uv run pyrig init
```

--------------------------------

### Subclassing PackageManager for Custom Dependency Installation (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/package_manager.md

Demonstrates how to subclass the PackageManager from pyrig to modify the behavior of dependency installation. This example adds a '--frozen' flag to the arguments passed to the superclass's install_dependencies_args method.

```python
# myapp/rig/tools/package_manager.py
from pyrig.rig.tools.package_manager import PackageManager as BasePM
from pyrig.src.processes import Args

class PackageManager(BasePM):
    def install_dependencies_args(self, *args: str) -> Args:
        return super().install_dependencies_args("--frozen", *args)
```

--------------------------------

### Build and Serve MkDocs Documentation (Bash)

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/mkdocs.md

Commands to build the static MkDocs site or serve it locally with live reloading. These commands are executed using `uv run` to ensure the correct Python environment is used.

```bash
# Serve documentation locally with live reload
uv run mkdocs serve

# Build static site
uv run mkdocs build

```

--------------------------------

### Initialize New Project with pyrig

Source: https://context7.com/winipedia/pyrig/llms.txt

Initializes a new Python project with pyrig, setting up Git, dependencies, project structure, tests, hooks, and an initial commit. It assumes the repository is already cloned and uv is used for dependency management.

```bash
# Create repository on GitHub, then clone it
git clone https://github.com/username/my-project.git
cd my-project

# Initialize with uv and pyrig
uv init
uv add pyrig
uv run pyrig init

# Push to GitHub
git push -u origin main
```

--------------------------------

### Override WorkflowConfigFile for Docker Setup

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/container_engine.md

This Python snippet demonstrates how to override the 'step_install_container_engine' method in WorkflowConfigFile to use the 'docker/setup-buildx-action@v3' GitHub Action, replacing the default Podman setup.

```python
# myapp/rig/configs/base/workflow.py
from pyrig.rig.configs.base.workflow import WorkflowConfigFile as BaseWorkflowConfigFile

class WorkflowConfigFile(BaseWorkflowConfigFile):

    def step_install_container_engine(self, *, step=None):
        return self.step(
            step_func=self.step_install_container_engine,
            uses="docker/setup-buildx-action@v3",
            step=step,
        )
```

--------------------------------

### Define Service-Specific Configuration in Python

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/example-usage.md

Demonstrates how to create a service-specific configuration file using Python. This involves subclassing `YamlConfigFile` and defining the `_configs` method to return a `ConfigDict` representing the service's settings.

```python
from pathlib import Path
from pyrig.rig.configs.base.base import ConfigDict
from pyrig.rig.configs.base.yaml import YamlConfigFile


class AuthConfigFile(YamlConfigFile):
    """JWT and OAuth configuration."""


    def parent_path(self) -> Path:
        return Path("config")


    def _configs(self) -> ConfigDict:
        return {
            "auth": {
                "jwt_algorithm": "RS256",
                "token_expiry": 3600,
                "oauth_providers": ["google", "github"]
            }
        }
```

--------------------------------

### Override Container Engine Installation in Workflow (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/architecture.md

Demonstrates how to subclass a BuildWorkflowConfigFile to change the container engine installation step from Podman to Docker. This is necessary when the base workflow hardcodes specific actions.

```python
# pyrig/rig/configs/base/workflow.py
def step_install_container_engine(self, ...):
    return self.step(
        uses="redhat-actions/podman-install@main",  # Hardcoded!
        ...
    )
```

```python
# myapp/rig/configs/workflows/build.py
from pyrig.rig.configs.workflows.build import BuildWorkflowConfigFile as BaseBuildWorkflowConfigFile

class BuildWorkflowConfigFile(BaseBuildWorkflowConfigFile):

    def step_install_container_engine(self, *, step=None):
        return self.step(
            step_func=self.step_install_container_engine,
            uses="docker/setup-buildx-action@v3",
            step=step,
        )

```

--------------------------------

### Install Podman Container Engine

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/workflows/build.md

This action installs the Podman container engine on the build runner. It uses the 'GITHUB_TOKEN' for authentication, enabling subsequent container build and management operations.

```yaml
steps:
  - name: Install Container Engine
    uses: redhat-actions/podman-install@main
```

--------------------------------

### Automatic Project Root Creation using pyrig

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/configs_init.md

This bash command initiates the automatic creation of the project's root structure, including the configs package and its __init__.py file. It leverages the pyrig tool to set up the necessary directories and files according to predefined configurations.

```bash
uv run pyrig mkroot

```

--------------------------------

### PyRig Source and Test Code Example

Source: https://github.com/winipedia/pyrig/blob/main/docs/tests/structure.md

Provides a concrete example of a source Python class and its corresponding required test class in PyRig. It demonstrates the naming conventions and structure for classes and methods.

```python
# Source: myapp/src/calculator.py
class Calculator:
    def add(self, a: int, b: int) -> int:
        return a + b

    def subtract(self, a: int, b: int) -> int:
        return a - b

# Required: tests/test_myapp/test_src/test_calculator.py
class TestCalculator:
    def test_add(self) -> None:
        calc = Calculator()
        assert calc.add(2, 3) == 5

    def test_subtract(self) -> None:
        calc = Calculator()
        assert calc.subtract(5, 3) == 2
```

--------------------------------

### Install and Manage Python Packages with uv

Source: https://github.com/winipedia/pyrig/blob/main/docs/more/tooling.md

The `uv` tool is a fast, modern Python package and project manager that handles dependency installation, package addition, and command execution within virtual environments. It aims to replace traditional tools like pip and poetry.

```bash
uv sync              # Install dependencies
uv add package       # Add dependency
uv run pytest        # Run command in venv
uv version --bump patch  # Bump version
```

--------------------------------

### Ensure Source Code Excludes Development Dependencies

Source: https://github.com/winipedia/pyrig/blob/main/docs/tests/autouse.md

Validates that the source code does not include development dependencies. It achieves this by copying the project to a temporary directory, installing dependencies without the 'dev' group, checking the install output, importing all modules in `src/`, and verifying the CLI works via `uv run --no-group dev <project> --help`. This assertion is skipped if no internet connection is available.

```python
def assert_src_runs_without_dev_deps():
    """Verify source code has no dev dependencies."""
    # Copies project to temp directory
    # Installs dependencies with `uv sync --no-group dev`
    # Verifies no dev dependencies appear in install output
    # Imports all modules in `src/` to catch dev dependency imports
    # Runs `uv run --no-group dev <project> --help` to verify CLI works
    # Skipped if no internet connection is available
    pass
```

--------------------------------

### Create __init__.py Files with pyrig mkinits

Source: https://context7.com/winipedia/pyrig/llms.txt

Scans the project for namespace packages and creates any missing `__init__.py` files to ensure correct Python package structure. Use the verbose flag (`-v`) for detailed output.

```bash
# Create missing __init__.py files
uv run pyrig mkinits

# With verbose output
uv run pyrig -v mkinits
```

--------------------------------

### Creating Documentation Pages (Bash)

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/mkdocs.md

Commands to create new markdown files and directories within the 'docs/' folder for organizing documentation. This is a prerequisite for adding new pages to the site navigation.

```bash
mkdir -p docs/guide
echo "# Installation" > docs/guide/installation.md
```

--------------------------------

### Add Runtime Dependency with uv

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/pyproject.md

This command adds a package to the project's runtime dependencies using the 'uv add' command. The specified package 'some-package' will be installed and tracked for runtime use.

```bash
uv add some-package
```

--------------------------------

### Run PyRig Build Command

Source: https://github.com/winipedia/pyrig/blob/main/docs/cli/commands/build.md

Demonstrates how to execute the PyRig build command with different verbosity levels. This command discovers and invokes builder configurations to create project artifacts.

```bash
uv run pyrig build

# With verbose output to see build details
uv run pyrig -v build

# With detailed logging including module names
uv run pyrig -vv build
```

--------------------------------

### Linter Tool Usage Example - Python

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/index.md

This Python code snippet demonstrates how to use the Linter tool wrapper from Pyrig. It shows how to access and print the command arguments for checking, and then how to execute those arguments.

```python
from pyrig.rig.tools.linter import Linter

# Get command arguments
args = Linter.I.check_args()
print(args)  # ruff check

# Execute
args.run()
```

--------------------------------

### Define PyRig CLI Entry Point

Source: https://github.com/winipedia/pyrig/blob/main/docs/configs/pyproject.md

Configures the main entry point for the project's command-line interface using PyRig. This creates an executable command that leverages PyRig's infrastructure to discover and run subcommands automatically. It can be invoked via `uv run my-app <command>` or directly as `my-app <command>` after activating the virtual environment.

```python
my-app = "pyrig.rig.cli.cli:main"      # Creates CLI command: my-app
```

--------------------------------

### Subclass VersionController to Sign Commits (Python)

Source: https://github.com/winipedia/pyrig/blob/main/docs/tools/version_controller.md

Demonstrates subclassing the pyrig VersionController to automatically sign Git commits. This example extends the base functionality by adding the '-S' flag to commit arguments.

```python
from pyrig.rig.tools.version_controller import VersionController as BaseVC
from pyrig.src.processes import Args

class VersionController(BaseVC):
    def commit_args(self, *args: str) -> Args:
        # Always sign commits
        return super().commit_args("-S", *args)
```