rhiza 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

rhiza/__init__.py

@@ -0,0 +1,9 @@
+"""Utility tools and command-line helpers for the Rhiza project.
+
+This package groups small, user-facing utilities that can be invoked from
+the command line or other automation scripts.
+"""
+
+from rhiza.models import RhizaTemplate
+
+__all__ = ["RhizaTemplate"]

rhiza/__main__.py

@@ -0,0 +1,10 @@
+"""Rhiza module entry point.
+
+This module allows running the Rhiza CLI with `python -m rhiza` by
+delegating execution to the Typer application defined in `rhiza.cli`.
+"""
+
+from rhiza.cli import app
+
+if __name__ == "__main__":
+    app()

rhiza/cli.py

@@ -0,0 +1,115 @@
+"""Rhiza command-line interface (CLI).
+
+This module defines the Typer application entry points exposed by Rhiza.
+Commands are thin wrappers around implementations in `rhiza.commands.*`.
+"""
+
+from pathlib import Path
+
+import typer
+
+from rhiza.commands.init import init as init_cmd
+from rhiza.commands.materialize import materialize as materialize_cmd
+from rhiza.commands.validate import validate as validate_cmd
+
+app = typer.Typer(
+    help="Rhiza - Manage reusable configuration templates for Python projects",
+    add_completion=True,
+)
+
+
+@app.command()
+def init(
+    target: Path = typer.Argument(
+        default=Path("."),  # default to current directory
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        help="Target directory (defaults to current directory)",
+    ),
+):
+    """Initialize or validate .github/template.yml.
+
+    Creates a default .github/template.yml configuration file if one doesn't
+    exist, or validates the existing configuration.
+
+    The default template includes common Python project files:
+    - .github (workflows, actions, etc.)
+    - .editorconfig
+    - .gitignore
+    - .pre-commit-config.yaml
+    - Makefile
+    - pytest.ini
+
+    Examples:
+        rhiza init
+        rhiza init /path/to/project
+        rhiza init ..
+    """
+    init_cmd(target)
+
+
+@app.command()
+def materialize(
+    target: Path = typer.Argument(
+        default=Path("."),  # default to current directory
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        help="Target git repository (defaults to current directory)",
+    ),
+    branch: str = typer.Option("main", "--branch", "-b", help="Rhiza branch to use"),
+    force: bool = typer.Option(False, "--force", "-y", help="Overwrite existing files"),
+):
+    """Inject Rhiza configuration templates into a target repository.
+
+    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.
+
+    Examples:
+        rhiza materialize
+        rhiza materialize --branch develop
+        rhiza materialize --force
+        rhiza materialize /path/to/project -b v2.0 -y
+    """
+    materialize_cmd(target, branch, force)
+
+
+@app.command()
+def validate(
+    target: Path = typer.Argument(
+        default=Path("."),  # default to current directory
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        help="Target git repository (defaults to current directory)",
+    ),
+):
+    """Validate Rhiza template configuration.
+
+    Validates the .github/template.yml file to ensure it is syntactically
+    correct and semantically valid. Performs comprehensive validation:
+
+    - Checks if template.yml exists
+    - Validates YAML syntax
+    - Verifies required fields are present (template-repository, include)
+    - Validates field types and formats
+    - Ensures repository name follows owner/repo format
+    - Confirms include paths are not empty
+
+    Returns exit code 0 on success, 1 on validation failure.
+
+    Examples:
+        rhiza validate
+        rhiza validate /path/to/project
+        rhiza validate ..
+    """
+    if not validate_cmd(target):
+        raise typer.Exit(code=1)

rhiza/commands/__init__.py

@@ -0,0 +1,5 @@
+"""Command implementations for the Rhiza CLI.
+
+This package contains the functions that back Typer commands exposed by
+`rhiza.cli`, such as `hello` and `inject`.
+"""

rhiza/commands/init.py

@@ -0,0 +1,66 @@
+"""Command to initialize or validate .github/template.yml.
+
+This module provides the init command that creates or validates the
+.github/template.yml file, which defines where templates come from
+and what paths are governed by Rhiza.
+"""
+
+from pathlib import Path
+
+from loguru import logger
+
+from rhiza.commands.validate import validate
+from rhiza.models import RhizaTemplate
+
+
+def init(target: Path):
+    """Initialize or validate .github/template.yml in the target repository.
+
+    Creates a default .github/template.yml file if it doesn't exist,
+    or validates an existing one.
+
+    Parameters
+    ----------
+    target:
+        Path to the target directory. Defaults to the current working directory.
+    """
+    # Convert to absolute path to avoid surprises
+    target = target.resolve()
+
+    logger.info(f"Initializing Rhiza configuration in: {target}")
+
+    # Create .github directory if it doesn't exist
+    github_dir = target / ".github"
+    github_dir.mkdir(parents=True, exist_ok=True)
+
+    # Define the template file path
+    template_file = github_dir / "template.yml"
+
+    if not template_file.exists():
+        # Create default template.yml
+        logger.info("Creating default .github/template.yml")
+
+        default_template = RhizaTemplate(
+            template_repository="jebel-quant/rhiza",
+            template_branch="main",
+            include=[
+                ".github",
+                ".editorconfig",
+                ".gitignore",
+                ".pre-commit-config.yaml",
+                "Makefile",
+                "pytest.ini",
+            ],
+        )
+
+        default_template.to_yaml(template_file)
+
+        logger.success("✓ Created .github/template.yml")
+        logger.info("""
+Next steps:
+  1. Review and customize .github/template.yml to match your project needs
+  2. Run 'rhiza materialize' to inject templates into your repository
+""")
+
+    # the template file exists, so validate it
+    validate(target)

rhiza/commands/materialize.py

@@ -0,0 +1,140 @@
+"""Command-line helpers for working with Rhiza templates.
+
+This module currently exposes a thin wrapper that shells out to the
+`tools/inject_rhiza.sh` script. It exists so the functionality can be
+invoked via a Python entry point while delegating the heavy lifting to
+the maintained shell script.
+"""
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from loguru import logger
+
+from rhiza.commands.init import init
+from rhiza.models import RhizaTemplate
+
+
+def expand_paths(base_dir: Path, paths: list[str]) -> list[Path]:
+    """Expand files/directories relative to base_dir into a flat list of files.
+
+    Given a list of paths relative to ``base_dir``, return a flat list of all
+    individual files.
+    """
+    all_files = []
+    for p in paths:
+        full_path = base_dir / p
+        if full_path.is_file():
+            all_files.append(full_path)
+        elif full_path.is_dir():
+            all_files.extend([f for f in full_path.rglob("*") if f.is_file()])
+        else:
+            # Path does not exist — could log a warning
+            continue
+    return all_files
+
+
+def materialize(target: Path, branch: str, force: bool):
+    """Materialize rhiza templates into TARGET repository."""
+    # Convert to absolute path to avoid surprises
+    target = target.resolve()
+
+    logger.info(f"Target repository: {target}")
+    logger.info(f"Rhiza branch: {branch}")
+
+    # -----------------------
+    # Ensure template.yml
+    # -----------------------
+    template_file = target / ".github" / "template.yml"
+    # template_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Initialize rhiza if not already initialized, e.g. construct a template.yml file
+    init(target)
+
+    # -----------------------
+    # Load template.yml
+    # -----------------------
+    template = RhizaTemplate.from_yaml(template_file)
+
+    rhiza_repo = template.template_repository
+    # Use template branch if specified, otherwise fall back to CLI parameter
+    rhiza_branch = template.template_branch if template.template_branch else branch
+    include_paths = template.include
+    excluded_paths = template.exclude
+
+    if not include_paths:
+        logger.error("No include paths found in template.yml")
+        raise sys.exit(1)
+
+    logger.info("Include paths:")
+    for p in include_paths:
+        logger.info(f"  - {p}")
+
+    # -----------------------
+    # Sparse clone rhiza
+    # -----------------------
+    tmp_dir = Path(tempfile.mkdtemp())
+    logger.info(f"Cloning {rhiza_repo}@{rhiza_branch} into temporary directory")
+
+    try:
+        subprocess.run(
+            [
+                "git",
+                "clone",
+                "--depth",
+                "1",
+                "--filter=blob:none",
+                "--sparse",
+                "--branch",
+                rhiza_branch,
+                f"https://github.com/{rhiza_repo}.git",
+                str(tmp_dir),
+            ],
+            check=True,
+            stdout=subprocess.DEVNULL,
+        )
+
+        subprocess.run(["git", "sparse-checkout", "init"], cwd=tmp_dir, check=True)
+        subprocess.run(["git", "sparse-checkout", "set", "--skip-checks", *include_paths], cwd=tmp_dir, check=True)
+
+        # After sparse-checkout
+        all_files = expand_paths(tmp_dir, include_paths)
+
+        # Filter out excluded files
+        # excluded_set = {tmp_dir / e for e in excluded_paths}
+        excluded_files = expand_paths(tmp_dir, excluded_paths)
+
+        files_to_copy = [f for f in all_files if f not in excluded_files]
+        # print(files_to_copy)
+
+        # Copy loop
+        for src_file in files_to_copy:
+            dst_file = target / src_file.relative_to(tmp_dir)
+            if dst_file.exists() and not force:
+                logger.warning(f"{dst_file.relative_to(target)} already exists — use force=True to overwrite")
+                continue
+
+            dst_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_file, dst_file)
+            logger.success(f"[ADD] {dst_file.relative_to(target)}")
+
+    finally:
+        shutil.rmtree(tmp_dir)
+
+    logger.success("Rhiza templates materialized successfully")
+    logger.info("""
+Next steps:
+  1. Review changes:
+       git status
+       git diff
+
+  2. Commit:
+       git add .
+       git commit -m "chore: import rhiza templates"
+
+This is a one-shot snapshot.
+Re-run this script to update templates explicitly.
+""")

rhiza/commands/validate.py

@@ -0,0 +1,140 @@
+"""Command for validating Rhiza template configuration.
+
+This module provides functionality to validate .github/template.yml files
+to ensure they are syntactically correct and semantically valid.
+"""
+
+from pathlib import Path
+
+import yaml
+from loguru import logger
+
+
+def validate(target: Path) -> bool:
+    """Validate template.yml configuration in the target repository.
+
+    Performs authoritative validation of the template configuration:
+    - Checks if template.yml exists
+    - Validates YAML syntax
+    - Validates required fields
+    - Validates field values are appropriate
+
+    Parameters
+    ----------
+    target:
+        Path to the target Git repository directory.
+
+    Returns:
+    -------
+    bool
+        True if validation passes, False otherwise.
+    """
+    # Convert to absolute path
+    target = target.resolve()
+
+    # Check if target is a git repository
+    if not (target / ".git").is_dir():
+        logger.error(f"Target directory is not a git repository: {target}")
+        return False
+
+    logger.info(f"Validating template configuration in: {target}")
+
+    # Check if template.yml exists
+    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")
+        return False
+
+    logger.success(f"Found template file: {template_file}")
+
+    # Validate YAML syntax
+    try:
+        with open(template_file) as f:
+            config = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        logger.error(f"Invalid YAML syntax in template.yml: {e}")
+        return False
+
+    if config is None:
+        logger.error("template.yml is empty")
+        return False
+
+    logger.success("YAML syntax is valid")
+
+    # Validate required fields
+    required_fields = {
+        "template-repository": str,
+        "include": list,
+    }
+
+    validation_passed = True
+
+    for field, expected_type in required_fields.items():
+        if field not in config:
+            logger.error(f"Missing required field: {field}")
+            validation_passed = False
+        elif not isinstance(config[field], expected_type):
+            logger.error(
+                f"Field '{field}' must be of type {expected_type.__name__}, got {type(config[field]).__name__}"
+            )
+            validation_passed = False
+        else:
+            logger.success(f"Field '{field}' is present and valid")
+
+    # Validate template-repository format
+    if "template-repository" in config:
+        repo = config["template-repository"]
+        if not isinstance(repo, str):
+            logger.error(f"template-repository must be a string, got {type(repo).__name__}")
+            validation_passed = False
+        elif "/" not in repo:
+            logger.error(f"template-repository must be in format 'owner/repo', got: {repo}")
+            validation_passed = False
+        else:
+            logger.success(f"template-repository format is valid: {repo}")
+
+    # Validate include paths
+    if "include" in config:
+        include = config["include"]
+        if not isinstance(include, list):
+            logger.error(f"include must be a list, got {type(include).__name__}")
+            validation_passed = False
+        elif len(include) == 0:
+            logger.error("include list cannot be empty")
+            validation_passed = False
+        else:
+            logger.success(f"include list has {len(include)} path(s)")
+            for path in include:
+                if not isinstance(path, str):
+                    logger.warning(f"include path should be a string, got {type(path).__name__}: {path}")
+                else:
+                    logger.info(f"  - {path}")
+
+    # Validate optional fields
+    if "template-branch" in config:
+        branch = config["template-branch"]
+        if not isinstance(branch, str):
+            logger.warning(f"template-branch should be a string, got {type(branch).__name__}: {branch}")
+        else:
+            logger.success(f"template-branch is valid: {branch}")
+
+    if "exclude" in config:
+        exclude = config["exclude"]
+        if not isinstance(exclude, list):
+            logger.warning(f"exclude should be a list, got {type(exclude).__name__}")
+        else:
+            logger.success(f"exclude list has {len(exclude)} path(s)")
+            for path in exclude:
+                if not isinstance(path, str):
+                    logger.warning(f"exclude path should be a string, got {type(path).__name__}: {path}")
+                else:
+                    logger.info(f"  - {path}")
+
+    # Final verdict
+    if validation_passed:
+        logger.success("✓ Validation passed: template.yml is valid")
+        return True
+    else:
+        logger.error("✗ Validation failed: template.yml has errors")
+        return False

rhiza/models.py

@@ -0,0 +1,103 @@
+"""Data models for Rhiza configuration.
+
+This module defines dataclasses that represent the structure of Rhiza
+configuration files, making it easier to work with them without frequent
+YAML parsing.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class RhizaTemplate:
+    """Represents the structure of .github/template.yml.
+
+    Attributes:
+    ----------
+    template_repository : str | None
+        The GitHub repository containing templates (e.g., "jebel-quant/rhiza").
+        Can be None if not specified in the template file.
+    template_branch : str | None
+        The branch to use from the template repository.
+        Can be None if not specified in the template file (defaults to "main" when creating).
+    include : list[str]
+        List of paths to include from the template repository.
+    exclude : list[str]
+        List of paths to exclude from the template repository (default: empty list).
+    """
+
+    template_repository: str | None = None
+    template_branch: str | None = None
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_yaml(cls, file_path: Path) -> "RhizaTemplate":
+        """Load RhizaTemplate from a YAML file.
+
+        Parameters
+        ----------
+        file_path : Path
+            Path to the template.yml file.
+
+        Returns:
+        -------
+        RhizaTemplate
+            The loaded template configuration.
+
+        Raises:
+        ------
+        FileNotFoundError
+            If the file does not exist.
+        yaml.YAMLError
+            If the YAML is malformed.
+        ValueError
+            If the file is empty.
+        """
+        with open(file_path) as f:
+            config = yaml.safe_load(f)
+
+        if not config:
+            raise ValueError("Template file is empty")
+
+        return cls(
+            template_repository=config.get("template-repository"),
+            template_branch=config.get("template-branch"),
+            include=config.get("include", []),
+            exclude=config.get("exclude", []),
+        )
+
+    def to_yaml(self, file_path: Path) -> None:
+        """Save RhizaTemplate to a YAML file.
+
+        Parameters
+        ----------
+        file_path : Path
+            Path where the template.yml file should be saved.
+        """
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Convert to dictionary with YAML-compatible keys
+        config = {}
+
+        # Only include template-repository if it's not None
+        if self.template_repository:
+            config["template-repository"] = self.template_repository
+
+        # Only include template-branch if it's not None
+        if self.template_branch:
+            config["template-branch"] = self.template_branch
+
+        # Include is always present as it's a required field for the config to be useful
+        config["include"] = self.include
+
+        # Only include exclude if it's not empty
+        if self.exclude:
+            config["exclude"] = self.exclude
+
+        with open(file_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)