rhiza 0.5.3__py3-none-any.whl → 0.5.4__py3-none-any.whl

rhiza/__init__.py

@@ -1,7 +1,57 @@
-"""Utility tools and command-line helpers for the Rhiza project.
+"""Rhiza — Manage reusable configuration templates for Python projects.
 
-This package groups small, user-facing utilities that can be invoked from
-the command line or other automation scripts.
+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

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/commands/__init__.py

@@ -1,7 +1,53 @@
 """Command implementations for the Rhiza CLI.
 
-This package contains the functions that back Typer commands exposed by
-`rhiza.cli`, such as `hello` and `inject`.
+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

rhiza/commands/materialize.py

@@ -37,18 +37,63 @@ def expand_paths(base_dir: Path, paths: list[str]) -> list[Path]:
     return all_files
 
 
-def materialize(target: Path, branch: str, force: bool) -> None:
+def materialize(target: Path, branch: str, target_branch: str | None, force: bool) -> None:
     """Materialize Rhiza templates into the target repository.
 
     This performs a sparse checkout of the template repository and copies
     the selected files into the target repository, recording all files
     under template control in `.rhiza.history`.
+
+    Parameters
+    ----------
+    target:
+        Path to the target repository.
+    branch:
+        The Rhiza template branch to use.
+    target_branch:
+        Optional branch name to create/checkout in target repository.
+    force:
+        Whether to overwrite existing files.
     """
     target = target.resolve()
 
     logger.info(f"Target repository: {target}")
     logger.info(f"Rhiza branch: {branch}")
 
+    # -----------------------
+    # Handle target branch creation/checkout if specified
+    # -----------------------
+    if target_branch:
+        logger.info(f"Creating/checking out target branch: {target_branch}")
+        try:
+            # Check if branch already exists
+            result = subprocess.run(
+                ["git", "rev-parse", "--verify", target_branch],
+                cwd=target,
+                capture_output=True,
+                text=True,
+            )
+
+            if result.returncode == 0:
+                # Branch exists, checkout
+                logger.info(f"Branch '{target_branch}' exists, checking out...")
+                subprocess.run(
+                    ["git", "checkout", target_branch],
+                    cwd=target,
+                    check=True,
+                )
+            else:
+                # Branch doesn't exist, create and checkout
+                logger.info(f"Creating new branch '{target_branch}'...")
+                subprocess.run(
+                    ["git", "checkout", "-b", target_branch],
+                    cwd=target,
+                    check=True,
+                )
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Failed to create/checkout branch '{target_branch}': {e}")
+            sys.exit(1)
+
     # -----------------------
     # Ensure Rhiza is initialized
     # -----------------------
@@ -63,6 +108,7 @@ def materialize(target: Path, branch: str, force: bool) -> None:
 
     rhiza_repo = template.template_repository
     rhiza_branch = template.template_branch or branch
+    rhiza_host = template.template_host or "github"
     include_paths = template.include
     excluded_paths = template.exclude
 
@@ -73,13 +119,23 @@ def materialize(target: Path, branch: str, force: bool) -> None:
     for p in include_paths:
         logger.info(f"  - {p}")
 
+    # -----------------------
+    # Construct git clone URL based on host
+    # -----------------------
+    if rhiza_host == "gitlab":
+        git_url = f"https://gitlab.com/{rhiza_repo}.git"
+    elif rhiza_host == "github":
+        git_url = f"https://github.com/{rhiza_repo}.git"
+    else:
+        raise ValueError(f"Unsupported template-host: {rhiza_host}. Must be 'github' or 'gitlab'.")
+
     # -----------------------
     # Sparse clone template repo
     # -----------------------
     tmp_dir = Path(tempfile.mkdtemp())
     materialized_files: list[Path] = []
 
-    logger.info(f"Cloning {rhiza_repo}@{rhiza_branch} into temporary directory")
+    logger.info(f"Cloning {rhiza_repo}@{rhiza_branch} from {rhiza_host} into temporary directory")
 
     try:
         subprocess.run(
@@ -92,7 +148,7 @@ def materialize(target: Path, branch: str, force: bool) -> None:
                 "--sparse",
                 "--branch",
                 rhiza_branch,
-                f"https://github.com/{rhiza_repo}.git",
+                git_url,
                 str(tmp_dir),
             ],
             check=True,

rhiza/commands/validate.py

@@ -39,7 +39,7 @@ def validate(target: Path) -> bool:
     template_file = target / ".github" / "template.yml"
     if not template_file.exists():
         logger.error(f"Template file not found: {template_file}")
-        logger.info("Run 'rhiza materialize' or 'rhiza inject' to create a default template.yml")
+        logger.info("Run 'rhiza init' to create a default template.yml")
         return False
 
     logger.success(f"Found template file: {template_file}")
@@ -115,6 +115,15 @@ def validate(target: Path) -> bool:
         else:
             logger.success(f"template-branch is valid: {branch}")
 
+    if "template-host" in config:
+        host = config["template-host"]
+        if not isinstance(host, str):
+            logger.warning(f"template-host should be a string, got {type(host).__name__}: {host}")
+        elif host not in ("github", "gitlab"):
+            logger.warning(f"template-host should be 'github' or 'gitlab', got: {host}")
+        else:
+            logger.success(f"template-host is valid: {host}")
+
     if "exclude" in config:
         exclude = config["exclude"]
         if not isinstance(exclude, list):

rhiza/models.py

@@ -16,16 +16,19 @@ class RhizaTemplate:
     """Represents the structure of .github/template.yml.
 
     Attributes:
-        template_repository: The GitHub repository containing templates (e.g., "jebel-quant/rhiza").
+        template_repository: The GitHub or GitLab repository containing templates (e.g., "jebel-quant/rhiza").
             Can be None if not specified in the template file.
         template_branch: The branch to use from the template repository.
             Can be None if not specified in the template file (defaults to "main" when creating).
+        template_host: The git hosting platform ("github" or "gitlab").
+            Defaults to "github" if not specified in the template file.
         include: List of paths to include from the template repository.
         exclude: List of paths to exclude from the template repository (default: empty list).
     """
 
     template_repository: str | None = None
     template_branch: str | None = None
+    template_host: str = "github"
     include: list[str] = field(default_factory=list)
     exclude: list[str] = field(default_factory=list)
 
@@ -53,6 +56,7 @@ class RhizaTemplate:
         return cls(
             template_repository=config.get("template-repository"),
             template_branch=config.get("template-branch"),
+            template_host=config.get("template-host", "github"),
             include=config.get("include", []),
             exclude=config.get("exclude", []),
         )
@@ -77,6 +81,10 @@ class RhizaTemplate:
         if self.template_branch:
             config["template-branch"] = self.template_branch
 
+        # Only include template-host if it's not the default "github"
+        if self.template_host and self.template_host != "github":
+            config["template-host"] = self.template_host
+
         # Include is always present as it's a required field for the config to be useful
         config["include"] = self.include
 

{rhiza-0.5.3.dist-info → rhiza-0.5.4.dist-info}/METADATA

@@ -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.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+rhiza/__init__.py,sha256=1jfkGAONm7dH4KwYjvNEyuxrQ-1m2YncxREYCJnTrHA,1933
+rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
+rhiza/cli.py,sha256=orVHOn569qHm-TffRLpSoJlF5x59dNfQsC2pX7VppYA,4721
+rhiza/models.py,sha256=R2nu_bf-j-U0kPfQXg6u-MSykrdGO9ixOzZoWy8mLCc,3448
+rhiza/commands/__init__.py,sha256=lIkN15MIat-wn9CB1cgUjTzTUQB95LBBAKFK1sGHdCc,1836
+rhiza/commands/init.py,sha256=QsOV_VBnRfSPebydH-fMe3haadboNIAYlOpAIYHtgUs,1936
+rhiza/commands/materialize.py,sha256=PcJT7Cq1eXoUZjAe_X1TXn4yUXt1Kft7rCedEe2P-44,7921
+rhiza/commands/validate.py,sha256=_0t9kfylMncm9JmKULn5e7V71XcQdFjlrtuOqZeshPM,5282
+rhiza-0.5.4.dist-info/METADATA,sha256=2Dh1FhzIIHbDvGu2FSPGHJCG8PQonP9rcZvO4D3MH-M,21278
+rhiza-0.5.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rhiza-0.5.4.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
+rhiza-0.5.4.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+rhiza-0.5.4.dist-info/RECORD,,

rhiza-0.5.3.dist-info/RECORD

@@ -1,13 +0,0 @@
-rhiza/__init__.py,sha256=KHBklJoM7XnW9oXCZqO2Cn-EHvo2z8m3IzzJA06W4qY,441
-rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
-rhiza/cli.py,sha256=20pzeIocwaPRQPtvjb4cguiXg8RGhfRkrn3FtNq9I0Q,4224
-rhiza/models.py,sha256=-n5eyPcU35IVsbvy7F-kyKR343TkOrx25kooLCF9whg,3001
-rhiza/commands/__init__.py,sha256=KcoFX52xQ1NFdgVeGsAkIaqmJrRso1GOq0vFL0WEB44,300
-rhiza/commands/init.py,sha256=QsOV_VBnRfSPebydH-fMe3haadboNIAYlOpAIYHtgUs,1936
-rhiza/commands/materialize.py,sha256=7_LqDBrdRHmsmG50LIJ7aHBeXEj4TW8TwSsmUUYg8aE,5877
-rhiza/commands/validate.py,sha256=7K69mP1Z42JLYKf2H1egQcR5qhFKlTAE61vYvowvoI4,4884
-rhiza-0.5.3.dist-info/METADATA,sha256=MCD0DNFBrNPRmt5SMtk5cDGNuCczWhrHeVi4yT_scbo,19938
-rhiza-0.5.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rhiza-0.5.3.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
-rhiza-0.5.3.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
-rhiza-0.5.3.dist-info/RECORD,,