rhiza 0.5.3__tar.gz → 0.5.4__tar.gz

rhiza-0.5.4/.github/workflows/sym2.yml

@@ -0,0 +1,134 @@
+name: SYM2
+# This workflow materializes rhiza templates using the update_rhiza branch
+# and creates a pull request with the changes.
+# IMPORTANT: When workflow files (.github/workflows/*.yml) are modified,
+# a Personal Access Token (PAT) with 'workflow' scope is required.
+# The PAT_TOKEN secret must be set in repository secrets.
+# See .github/TOKEN_SETUP.md for setup instructions.
+
+permissions:
+  contents: write
+  pull-requests: write
+
+
+on:
+  workflow_dispatch:
+    inputs:
+      create-pr:
+        description: "Create a pull request"
+        type: boolean
+        default: true
+
+jobs:
+  materialize:
+    if: ${{ github.ref_name != 'update_rhiza' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.PAT_TOKEN }}
+          fetch-depth: 0
+
+      - name: Check PAT_TOKEN configuration
+        shell: bash
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          if [ -z "$PAT_TOKEN" ]; then
+            echo "::warning::PAT_TOKEN secret is not configured."
+            echo "::warning::If this materialize modifies workflow files, the push will fail."
+            echo "::warning::See .github/TOKEN_SETUP.md for setup instructions."
+          else
+            echo "✓ PAT_TOKEN is configured."
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Materialize rhiza templates
+        id: materialize
+        shell: bash
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          git checkout -B update_rhiza
+
+          uvx rhiza materialize --force --branch update_rhiza .
+
+          git add -A
+
+          if git diff --cached --quiet; then
+            echo "No changes detected."
+            {
+              echo "changes_detected=false"
+              echo "workflows_changed=false"
+              echo "push_succeeded=false"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "changes_detected=true" >> "$GITHUB_OUTPUT"
+
+          workflows_changed=false
+          can_push=true
+
+          if git diff --cached --name-only | grep -q '^\.github/workflows/'; then
+            workflows_changed=true
+            echo "workflows_changed=true" >> "$GITHUB_OUTPUT"
+            echo "⚠️ Workflow files modified."
+            echo ""
+            echo "ℹ️  Pushing workflow changes requires a PAT with 'workflow' scope."
+
+            if [ -n "$PAT_TOKEN" ]; then
+              git remote set-url origin \
+                "https://x-access-token:${PAT_TOKEN}@github.com/${{ github.repository }}.git"
+              echo "✓ Using PAT_TOKEN for authentication."
+            else
+              echo "::error::Workflow files changed but PAT_TOKEN secret is not set."
+              echo "::error::GitHub's security policy requires a Personal Access Token with 'workflow' scope to push workflow changes."
+              echo "::error::See .github/TOKEN_SETUP.md for instructions on creating and configuring the PAT_TOKEN secret."
+              can_push=false
+            fi
+          else
+            echo "workflows_changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git commit -m "chore: Materialize rhiza templates from update_rhiza branch"
+
+          if [ "$can_push" = true ]; then
+            if git push origin HEAD:update_rhiza --force-with-lease; then
+              echo "push_succeeded=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "push_succeeded=false" >> "$GITHUB_OUTPUT"
+              echo "::error::Failed to push branch 'update_rhiza'."
+              echo "::error::If workflow files were changed, this is likely because:"
+              echo "::error::  1. PAT_TOKEN secret is not set, OR"
+              echo "::error::  2. PAT_TOKEN lacks the 'workflow' scope"
+              echo "::error::See .github/TOKEN_SETUP.md for setup instructions."
+              exit 1
+            fi
+          else
+            echo "push_succeeded=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create pull request
+        if: ${{ inputs.create-pr && steps.materialize.outputs.changes_detected == 'true' && steps.materialize.outputs.push_succeeded == 'true' }}
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.PAT_TOKEN || github.token }}
+          base: ${{ github.event.repository.default_branch }}
+          branch: update_rhiza
+          delete-branch: false
+          title: "chore: Materialize rhiza templates from update_rhiza branch"
+          body: |
+            This pull request materializes rhiza templates using the `update_rhiza` branch.
+
+            Changes were generated automatically using **rhiza materialize --force --branch update_rhiza**.
+

{rhiza-0.5.3 → rhiza-0.5.4}/CLI.md

@@ -165,6 +165,9 @@ grep "myfile.txt" .rhiza.history
 # Required: Template repository (owner/repo format)
 template-repository: jebel-quant/rhiza
 
+# Optional: Hosting platform (default: github)
+template-host: github
+
 # Optional: Branch to use (default: main)
 template-branch: main
 
@@ -184,7 +187,8 @@ exclude:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `template-repository` | string | Yes | GitHub repo in `owner/repo` format |
+| `template-repository` | string | Yes | GitHub or GitLab repo in `owner/repo` format |
+| `template-host` | string | No | Hosting platform: `github` (default) or `gitlab` |
 | `template-branch` | string | No | Branch name (default: `main`) |
 | `include` | list | Yes | Paths to copy from template |
 | `exclude` | list | No | Paths to skip when copying |

{rhiza-0.5.3 → rhiza-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhiza
-Version: 0.5.3
+Version: 0.5.4
 Summary: Reusable configuration templates for modern Python projects
 Project-URL: Homepage, https://github.com/jebel-quant/rhiza-cli
 Project-URL: Repository, https://github.com/jebel-quant/rhiza-cli
@@ -370,9 +370,12 @@ Rhiza uses a `.github/template.yml` file to define template sources and what to
 The `template.yml` file uses YAML format with the following structure:
 
 ```yaml
-# Required: GitHub repository containing templates (format: owner/repo)
+# Required: GitHub or GitLab repository containing templates (format: owner/repo)
 template-repository: jebel-quant/rhiza
 
+# Optional: Git hosting platform (default: github)
+template-host: github
+
 # Optional: Branch to use from template repository (default: main)
 template-branch: main
 
@@ -398,8 +401,16 @@ exclude:
 
 - **Type:** String
 - **Format:** `owner/repository`
-- **Description:** GitHub repository containing your configuration templates
-- **Example:** `jebel-quant/rhiza`, `myorg/python-templates`
+- **Description:** GitHub or GitLab repository containing your configuration templates
+- **Example:** `jebel-quant/rhiza`, `myorg/python-templates`, `mygroup/gitlab-templates`
+
+#### `template-host` (optional)
+
+- **Type:** String
+- **Default:** `github`
+- **Options:** `github`, `gitlab`
+- **Description:** Git hosting platform where the template repository is hosted
+- **Example:** `github`, `gitlab`
 
 #### `template-branch` (optional)
 
@@ -443,6 +454,7 @@ exclude:
 
 ### Complete Configuration Example
 
+#### GitHub Example
 ```yaml
 template-repository: jebel-quant/rhiza
 template-branch: main
@@ -461,6 +473,21 @@ exclude:
   - .github/CODEOWNERS
 ```
 
+#### GitLab Example
+```yaml
+template-repository: mygroup/python-templates
+template-host: gitlab
+template-branch: main
+include:
+  - .gitlab-ci.yml
+  - .editorconfig
+  - .gitignore
+  - Makefile
+  - pytest.ini
+exclude:
+  - .gitlab-ci.yml
+```
+
 ## Examples
 
 ### Example 1: Setting up a new Python project
@@ -532,7 +559,29 @@ Then materialize:
 rhiza materialize --force
 ```
 
-### Example 4: Validating before CI/CD
+### Example 4: Using a GitLab template repository
+
+Edit `.github/template.yml`:
+
+```yaml
+template-repository: mygroup/python-templates
+template-host: gitlab
+template-branch: main
+include:
+  - .gitlab-ci.yml
+  - .editorconfig
+  - .gitignore
+  - Makefile
+  - pytest.ini
+```
+
+Then materialize:
+
+```bash
+rhiza materialize --force
+```
+
+### Example 5: Validating before CI/CD
 
 Add to your CI pipeline:
 
@@ -736,8 +785,9 @@ Run `rhiza validate` for detailed error messages.
 Ensure:
 1. The template repository exists and is accessible
 2. The specified branch exists
-3. You have network connectivity to GitHub
+3. You have network connectivity to GitHub or GitLab
 4. The repository is public (or you have appropriate credentials configured)
+5. The `template-host` field matches your repository's hosting platform (defaults to "github")
 
 ### Files not being copied
 
@@ -755,7 +805,18 @@ A: Yes, as long as you have Git credentials configured that allow access to the
 
 **Q: Does Rhiza support template repositories hosted outside GitHub?**
 
-A: Currently, Rhiza is designed for GitHub repositories. Support for other Git hosting services could be added in the future.
+A: Yes! Rhiza supports both GitHub and GitLab repositories. Use the `template-host` field in your `.github/template.yml` to specify "github" (default) or "gitlab".
+
+**Q: How do I use a GitLab repository as a template source?**
+
+A: Add `template-host: gitlab` to your `.github/template.yml` file. For example:
+```yaml
+template-repository: mygroup/myproject
+template-host: gitlab
+include:
+  - .gitlab-ci.yml
+  - Makefile
+```
 
 **Q: Can I materialize templates from multiple repositories?**
 

{rhiza-0.5.3 → rhiza-0.5.4}/README.md

@@ -337,9 +337,12 @@ Rhiza uses a `.github/template.yml` file to define template sources and what to
 The `template.yml` file uses YAML format with the following structure:
 
 ```yaml
-# Required: GitHub repository containing templates (format: owner/repo)
+# Required: GitHub or GitLab repository containing templates (format: owner/repo)
 template-repository: jebel-quant/rhiza
 
+# Optional: Git hosting platform (default: github)
+template-host: github
+
 # Optional: Branch to use from template repository (default: main)
 template-branch: main
 
@@ -365,8 +368,16 @@ exclude:
 
 - **Type:** String
 - **Format:** `owner/repository`
-- **Description:** GitHub repository containing your configuration templates
-- **Example:** `jebel-quant/rhiza`, `myorg/python-templates`
+- **Description:** GitHub or GitLab repository containing your configuration templates
+- **Example:** `jebel-quant/rhiza`, `myorg/python-templates`, `mygroup/gitlab-templates`
+
+#### `template-host` (optional)
+
+- **Type:** String
+- **Default:** `github`
+- **Options:** `github`, `gitlab`
+- **Description:** Git hosting platform where the template repository is hosted
+- **Example:** `github`, `gitlab`
 
 #### `template-branch` (optional)
 
@@ -410,6 +421,7 @@ exclude:
 
 ### Complete Configuration Example
 
+#### GitHub Example
 ```yaml
 template-repository: jebel-quant/rhiza
 template-branch: main
@@ -428,6 +440,21 @@ exclude:
   - .github/CODEOWNERS
 ```
 
+#### GitLab Example
+```yaml
+template-repository: mygroup/python-templates
+template-host: gitlab
+template-branch: main
+include:
+  - .gitlab-ci.yml
+  - .editorconfig
+  - .gitignore
+  - Makefile
+  - pytest.ini
+exclude:
+  - .gitlab-ci.yml
+```
+
 ## Examples
 
 ### Example 1: Setting up a new Python project
@@ -499,7 +526,29 @@ Then materialize:
 rhiza materialize --force
 ```
 
-### Example 4: Validating before CI/CD
+### Example 4: Using a GitLab template repository
+
+Edit `.github/template.yml`:
+
+```yaml
+template-repository: mygroup/python-templates
+template-host: gitlab
+template-branch: main
+include:
+  - .gitlab-ci.yml
+  - .editorconfig
+  - .gitignore
+  - Makefile
+  - pytest.ini
+```
+
+Then materialize:
+
+```bash
+rhiza materialize --force
+```
+
+### Example 5: Validating before CI/CD
 
 Add to your CI pipeline:
 
@@ -703,8 +752,9 @@ Run `rhiza validate` for detailed error messages.
 Ensure:
 1. The template repository exists and is accessible
 2. The specified branch exists
-3. You have network connectivity to GitHub
+3. You have network connectivity to GitHub or GitLab
 4. The repository is public (or you have appropriate credentials configured)
+5. The `template-host` field matches your repository's hosting platform (defaults to "github")
 
 ### Files not being copied
 
@@ -722,7 +772,18 @@ A: Yes, as long as you have Git credentials configured that allow access to the
 
 **Q: Does Rhiza support template repositories hosted outside GitHub?**
 
-A: Currently, Rhiza is designed for GitHub repositories. Support for other Git hosting services could be added in the future.
+A: Yes! Rhiza supports both GitHub and GitLab repositories. Use the `template-host` field in your `.github/template.yml` to specify "github" (default) or "gitlab".
+
+**Q: How do I use a GitLab repository as a template source?**
+
+A: Add `template-host: gitlab` to your `.github/template.yml` file. For example:
+```yaml
+template-repository: mygroup/myproject
+template-host: gitlab
+include:
+  - .gitlab-ci.yml
+  - Makefile
+```
 
 **Q: Can I materialize templates from multiple repositories?**
 

{rhiza-0.5.3 → rhiza-0.5.4}/USAGE.md

@@ -252,6 +252,37 @@ vim .github/template.yml  # Change template-branch to 'develop'
 rhiza materialize
 ```
 
+### Using GitLab Repositories
+
+Configure Rhiza to use a GitLab template repository:
+
+**Edit `.github/template.yml`:**
+
+```yaml
+template-repository: mygroup/python-templates
+template-host: gitlab
+template-branch: main
+include:
+  - .gitlab-ci.yml
+  - .editorconfig
+  - .gitignore
+  - Makefile
+  - pytest.ini
+exclude:
+  - .gitlab-ci.yml  # Example exclusion
+```
+
+**Materialize:**
+
+```bash
+rhiza materialize --force
+```
+
+**Notes:**
+- The `template-host` field supports `github` (default) and `gitlab`
+- Repository format is the same: `owner/repo` for GitHub or `group/project` for GitLab
+- All other Rhiza features work identically with GitLab repositories
+
 ### Selective Inclusion
 
 Include only specific files:

{rhiza-0.5.3 → rhiza-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rhiza"
-version = "0.5.3"
+version = "0.5.4"
 description = "Reusable configuration templates for modern Python projects"
 readme = "README.md"
 requires-python = ">=3.11"

rhiza-0.5.4/src/rhiza/__init__.py

@@ -0,0 +1,65 @@
+"""Rhiza — Manage reusable configuration templates for Python projects.
+
+Rhiza is a command‑line interface (CLI) that helps you maintain consistent
+configuration across multiple Python projects using templates stored in a
+central repository. It can initialize projects with standard configuration,
+materialize (inject) template files into a target repository, and validate the
+template configuration.
+
+## Key features
+
+- Template initialization for new or existing projects.
+- Template materialization with selective include/exclude support.
+- Configuration validation (syntax and basic semantics).
+- Multi‑host support (GitHub and GitLab).
+- Non‑destructive updates by default, with an explicit `--force` flag.
+
+## Quick start
+
+Initialize a project with Rhiza templates:
+
+```bash
+cd your-project
+rhiza init
+```
+
+Validate your configuration:
+
+```bash
+rhiza validate
+```
+
+Customize `.github/template.yml`, then materialize templates into your project:
+
+```bash
+rhiza materialize
+```
+
+## Main modules
+
+- `rhiza.commands` — Core command implementations (init, materialize, validate).
+- `rhiza.models` — Data models and schemas for template configuration.
+
+## Documentation
+
+For an overview and usage guides, see the repository files:
+
+- [README.md](https://github.com/jebel-quant/rhiza-cli/blob/main/README.md) —
+Project overview and installation instructions.
+- [USAGE.md](https://github.com/jebel-quant/rhiza-cli/blob/main/USAGE.md) —
+Practical examples, workflows, and best practices.
+- [CLI.md](https://github.com/jebel-quant/rhiza-cli/blob/main/CLI.md) —
+Command reference with examples.
+
+Latest version and updates: https://github.com/jebel-quant/rhiza-cli
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("rhiza")
+except PackageNotFoundError:
+    # Package is not installed, use a fallback version
+    __version__ = "0.0.0+dev"
+
+__all__ = ["commands", "models"]

{rhiza-0.5.3 → rhiza-0.5.4}/src/rhiza/cli.py

@@ -14,7 +14,13 @@ from rhiza.commands import materialize as materialize_cmd
 from rhiza.commands import validate as validate_cmd
 
 app = typer.Typer(
-    help="Rhiza - Manage reusable configuration templates for Python projects",
+    help=(
+        """
+        Rhiza - Manage reusable configuration templates for Python projects
+
+        \x1b]8;;https://jebel-quant.github.io/rhiza-cli/\x1b\\https://jebel-quant.github.io/rhiza-cli/\x1b]8;;\x1b\\
+        """
+    ),
     add_completion=True,
 )
 
@@ -64,11 +70,13 @@ def init(
         help="Target directory (defaults to current directory)",
     ),
 ):
-    """Initialize or validate .github/template.yml.
+    r"""Initialize or validate .github/template.yml.
 
-    Creates a default .github/template.yml configuration file if one doesn't
-    exist, or validates the existing configuration.
+    \b
+    Creates a default `.github/template.yml` configuration file if one
+    doesn't exist, or validates the existing configuration.
 
+    \b
     The default template includes common Python project files:
     - .github (workflows, actions, etc.)
     - .editorconfig
@@ -77,10 +85,11 @@ def init(
     - Makefile
     - pytest.ini
 
+    \b
     Examples:
-        rhiza init
-        rhiza init /path/to/project
-        rhiza init ..
+      rhiza init
+      rhiza init /path/to/project
+      rhiza init ..
     """
     init_cmd(target)
 
@@ -95,27 +104,36 @@ def materialize(
         help="Target git repository (defaults to current directory)",
     ),
     branch: str = typer.Option("main", "--branch", "-b", help="Rhiza branch to use"),
+    target_branch: str = typer.Option(
+        None,
+        "--target-branch",
+        "--checkout-branch",
+        help="Create and checkout a new branch in the target repository for changes",
+    ),
     force: bool = typer.Option(False, "--force", "-y", help="Overwrite existing files"),
 ):
-    """Inject Rhiza configuration templates into a target repository.
+    r"""Inject Rhiza configuration templates into a target repository.
 
+    \b
     Materializes configuration files from the template repository specified
     in .github/template.yml into your project. This command:
 
-    1. Reads .github/template.yml configuration
-    2. Performs a sparse clone of the template repository
-    3. Copies specified files/directories to your project
-    4. Respects exclusion patterns defined in the configuration
-
-    Files that already exist will NOT be overwritten unless --force is used.
+    \b
+    - Reads .github/template.yml configuration
+    - Performs a sparse clone of the template repository
+    - Copies specified files/directories to your project
+    - Respects exclusion patterns defined in the configuration
+    - Files that already exist will NOT be overwritten unless --force is used.
 
+    \b
     Examples:
         rhiza materialize
         rhiza materialize --branch develop
         rhiza materialize --force
+        rhiza materialize --target-branch feature/update-templates
         rhiza materialize /path/to/project -b v2.0 -y
     """
-    materialize_cmd(target, branch, force)
+    materialize_cmd(target, branch, target_branch, force)
 
 
 @app.command()
@@ -128,11 +146,13 @@ def validate(
         help="Target git repository (defaults to current directory)",
     ),
 ):
-    """Validate Rhiza template configuration.
+    r"""Validate Rhiza template configuration.
 
     Validates the .github/template.yml file to ensure it is syntactically
-    correct and semantically valid. Performs comprehensive validation:
+    correct and semantically valid.
 
+    \b
+    Performs comprehensive validation:
     - Checks if template.yml exists
     - Validates YAML syntax
     - Verifies required fields are present (template-repository, include)
@@ -140,8 +160,10 @@ def validate(
     - Ensures repository name follows owner/repo format
     - Confirms include paths are not empty
 
+
     Returns exit code 0 on success, 1 on validation failure.
 
+    \b
     Examples:
         rhiza validate
         rhiza validate /path/to/project

rhiza-0.5.4/src/rhiza/commands/__init__.py

@@ -0,0 +1,55 @@
+"""Command implementations for the Rhiza CLI.
+
+This package contains the core implementation functions that back the Typer
+commands exposed by `rhiza.cli`. These commands help you manage reusable
+configuration templates for Python projects.
+
+## Available Commands
+
+### init
+
+Initialize or validate `.github/template.yml` in a target directory.
+
+Creates a default configuration file if it doesn't exist, or validates
+an existing one. The default configuration includes common Python project
+files like `.github`, `.editorconfig`, `.gitignore`,
+`.pre-commit-config.yaml`, `Makefile`, and `pytest.ini`.
+
+### materialize
+
+Inject Rhiza configuration templates into a target repository.
+
+Materializes template files from the configured template repository into
+your target project by performing a sparse clone of the template repository,
+copying specified files/directories, and respecting exclusion patterns.
+Files that already exist will not be overwritten unless the `--force` flag
+is used.
+
+### validate
+
+Validate Rhiza template configuration.
+
+Validates the `.github/template.yml` file to ensure it is syntactically
+correct and semantically valid. Performs comprehensive validation including
+YAML syntax checking, required field verification, field type validation,
+and repository format verification.
+
+## Usage Example
+
+These functions are typically invoked through the CLI:
+
+    ```bash
+    $ rhiza init                    # Initialize configuration
+
+    $ rhiza materialize             # Apply templates to project
+
+    $ rhiza validate                # Validate template configuration
+    ```
+
+For more detailed usage examples and workflows, see the USAGE.md guide
+or try rhiza <command> --help
+"""
+
+from .init import init  # noqa: F401
+from .materialize import materialize  # noqa: F401
+from .validate import validate  # noqa: F401