pyforge-init 0.1.0__py3-none-any.whl

pyforge/remote.py

@@ -0,0 +1,179 @@
+"""
+Remote GitHub template support for pyforge.
+
+Parses `gh:user/repo` and `gh:user/repo@ref` template strings,
+downloads the GitHub repository as a ZIP archive, and copies its
+contents into the target project directory (degit-style: plain file copy,
+no Jinja rendering).
+
+Template directory convention
+------------------------------
+If the downloaded repo contains a top-level `template/` directory, only
+that subdirectory is copied. Otherwise the entire repo root is copied.
+This lets template authors keep docs, CI config, etc. outside the
+scaffolded content.
+"""
+from __future__ import annotations
+
+import io
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def is_remote_template(template: str) -> bool:
+    """Return True if the template string refers to a remote GitHub repo."""
+    return template.startswith("gh:")
+
+
+def parse_gh_template(template: str) -> Tuple[str, str, str]:
+    """
+    Parse a `gh:user/repo@ref` string.
+
+    Returns:
+        (user, repo, ref)  — ref defaults to "main".
+
+    Raises:
+        ValueError: if the string cannot be parsed.
+    """
+    body = template[3:]  # strip "gh:"
+    ref = "main"
+
+    if "@" in body:
+        body, ref = body.rsplit("@", 1)
+
+    parts = body.split("/")
+    if len(parts) != 2 or not all(parts):
+        raise ValueError(
+            f"Invalid remote template '{template}'. "
+            "Expected format: gh:username/repo or gh:username/repo@ref"
+        )
+
+    user, repo = parts
+    return user, repo, ref
+
+
+def _zip_url(user: str, repo: str, ref: str) -> str:
+    return f"https://github.com/{user}/{repo}/archive/refs/heads/{ref}.zip"
+
+
+def _zip_url_tag(user: str, repo: str, ref: str) -> str:
+    """Alternative URL used when the ref is a tag rather than a branch."""
+    return f"https://github.com/{user}/{repo}/archive/refs/tags/{ref}.zip"
+
+
+def fetch_and_apply(template: str, project_path: Path) -> None:
+    """
+    Download a GitHub repo and copy its template content into *project_path*.
+
+    Uses a Rich spinner for visual feedback during the download.
+
+    Args:
+        template:     The `gh:user/repo[@ref]` string.
+        project_path: The (already created) destination project directory.
+
+    Raises:
+        RuntimeError: on network errors, 404s, or ZIP extraction failures.
+    """
+    import httpx
+    from rich.console import Console
+    from rich.progress import Progress, SpinnerColumn, TextColumn
+
+    console = Console()
+    user, repo, ref = parse_gh_template(template)
+
+    url = _zip_url(user, repo, ref)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+        console=console,
+    ) as progress:
+        task = progress.add_task(
+            f"[cyan]Fetching [bold]{user}/{repo}[/bold] @ {ref}…", total=None
+        )
+
+        zip_bytes = _download_zip(url, user, repo, ref)
+        progress.update(task, description=f"[cyan]Unpacking [bold]{user}/{repo}[/bold]…")
+        _extract_zip(zip_bytes, repo, ref, project_path)
+
+    console.print(
+        f"[green]✓ Remote template [bold]{user}/{repo}[/bold] applied.[/green]"
+    )
+
+
+def _download_zip(url: str, user: str, repo: str, ref: str) -> bytes:
+    """Download the ZIP, retrying the tag URL if the branch URL returns 404."""
+    import httpx
+
+    try:
+        response = httpx.get(url, follow_redirects=True, timeout=30)
+        if response.status_code == 404:
+            # Try interpreting the ref as a tag instead of a branch
+            tag_url = _zip_url_tag(user, repo, ref)
+            response = httpx.get(tag_url, follow_redirects=True, timeout=30)
+        response.raise_for_status()
+        return response.content
+    except httpx.HTTPStatusError as exc:
+        raise RuntimeError(
+            f"Could not download template from GitHub "
+            f"({exc.response.status_code}). "
+            f"Check that '{user}/{repo}' exists and ref '{ref}' is valid."
+        ) from exc
+    except httpx.RequestError as exc:
+        raise RuntimeError(
+            f"Network error while fetching template: {exc}"
+        ) from exc
+
+
+def _extract_zip(
+    zip_bytes: bytes,
+    repo: str,
+    ref: str,
+    project_path: Path,
+) -> None:
+    """
+    Extract the ZIP archive and copy the template content to project_path.
+
+    GitHub archives are wrapped in a top-level `<repo>-<ref>/` folder.
+    We strip that prefix, then look for an inner `template/` subdirectory.
+    If found, only its contents are copied; otherwise the whole archive root
+    is copied.
+    """
+    try:
+        with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+            # Determine the top-level prefix GitHub adds (e.g. "myrepo-main/")
+            names = zf.namelist()
+            if not names:
+                raise RuntimeError("Downloaded ZIP archive is empty.")
+
+            prefix = names[0].split("/")[0] + "/"
+
+            # Decide which sub-path to extract from inside the archive
+            template_prefix = prefix + "template/"
+            has_template_dir = any(n.startswith(template_prefix) for n in names)
+            source_prefix = template_prefix if has_template_dir else prefix
+
+            # Extract matching entries into the project directory
+            for member in zf.infolist():
+                if not member.filename.startswith(source_prefix):
+                    continue
+                # Compute relative path inside the project
+                relative = member.filename[len(source_prefix):]
+                if not relative:
+                    continue  # skip the directory entry itself
+
+                dest = project_path / relative
+
+                if member.is_dir():
+                    dest.mkdir(parents=True, exist_ok=True)
+                else:
+                    dest.parent.mkdir(parents=True, exist_ok=True)
+                    dest.write_bytes(zf.read(member.filename))
+
+    except zipfile.BadZipFile as exc:
+        raise RuntimeError(
+            f"Downloaded file is not a valid ZIP archive: {exc}"
+        ) from exc

pyforge/templates/basic/tests/test_main.py.jinja

@@ -0,0 +1,3 @@
+def test_example():
+    """Example test that always passes."""
+    assert True

pyforge/templates/cli/src/package/__main__.py.jinja

@@ -0,0 +1,4 @@
+from {{ project_name }}.cli import main
+
+if __name__ == "__main__":
+    main()

pyforge/templates/cli/src/package/cli.py.jinja

@@ -0,0 +1,7 @@
+import click
+
+@click.command()
+@click.option("--name", default="World", help="Who to greet.")
+def main(name: str):
+    """Simple CLI entrypoint."""
+    click.echo(f"Hello, {name}!")

pyforge/templates/cli/tests/test_cli.py.jinja

@@ -0,0 +1,8 @@
+from click.testing import CliRunner
+from {{ project_name }}.cli import main
+
+def test_main():
+    runner = CliRunner()
+    result = runner.invoke(main, ["--name", "Test"])
+    assert result.exit_code == 0
+    assert "Hello, Test!" in result.output

pyforge/templates/fastapi/src/package/main.py.jinja

@@ -0,0 +1,7 @@
+from fastapi import FastAPI
+
+app = FastAPI(title="{{ project_name }}")
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello, World!"}

pyforge/templates/fastapi/tests/test_main.py.jinja

@@ -0,0 +1,9 @@
+from fastapi.testclient import TestClient
+from {{ project_name }}.main import app
+
+client = TestClient(app)
+
+def test_read_root():
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello, World!"}

pyforge/templates/flask/src/package/app.py.jinja

@@ -0,0 +1,10 @@
+from flask import Flask
+
+def create_app():
+    app = Flask(__name__)
+
+    @app.route("/")
+    def hello():
+        return {"message": "Hello, World!"}
+
+    return app

pyforge/templates/flask/tests/test_app.py.jinja

@@ -0,0 +1,19 @@
+import pytest
+from {{ project_name }}.app import create_app
+
+@pytest.fixture
+def app():
+    app = create_app()
+    app.config.update({
+        "TESTING": True,
+    })
+    yield app
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+
+def test_hello(client):
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json == {"message": "Hello, World!"}

pyforge/templates/shared/Justfile.jinja

@@ -0,0 +1,28 @@
+install:
+    pip install -e ".[dev]"
+
+test:
+    pytest
+
+lint:
+    ruff check .
+
+format:
+    ruff format .
+
+run:
+{%- if template == 'fastapi' %}
+    uvicorn src.{{ project_name }}.main:app --reload
+{%- elif template == 'flask' %}
+    FLASK_APP=src/{{ project_name }}/app.py flask run
+{%- elif template == 'cli' %}
+    {{ project_name }}
+{%- else %}
+    python -m {{ project_name }}
+{%- endif %}
+
+clean:
+    find . -type d -name __pycache__ -exec rm -rf {} +
+    find . -type d -name .pytest_cache -exec rm -rf {} +
+    find . -type d -name .ruff_cache -exec rm -rf {} +
+    rm -rf build/ dist/ *.egg-info/

pyforge/templates/shared/Makefile.jinja

@@ -0,0 +1,30 @@
+.PHONY: install test lint format run clean
+
+install:
+	pip install -e ".[dev]"
+
+test:
+	pytest
+
+lint:
+	ruff check .
+
+format:
+	ruff format .
+
+run:
+{%- if template == 'fastapi' %}
+	uvicorn src.{{ project_name }}.main:app --reload
+{%- elif template == 'flask' %}
+	FLASK_APP=src/{{ project_name }}/app.py flask run
+{%- elif template == 'cli' %}
+	{{ project_name }}
+{%- else %}
+	python -m {{ project_name }}
+{%- endif %}
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name .pytest_cache -exec rm -rf {} +
+	find . -type d -name .ruff_cache -exec rm -rf {} +
+	rm -rf build/ dist/ *.egg-info/

pyforge/templates/shared/README.md.jinja

@@ -0,0 +1,28 @@
+# {{ project_name }}
+
+{{ description }}
+
+## Getting Started
+
+1. Set up your environment:
+   ```bash
+   {% if use_justfile %}just install{% else %}make install{% endif %}
+   ```
+{% if use_pre_commit %}
+2. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+{% endif %}
+
+## Development
+
+Run tests:
+```bash
+{% if use_justfile %}just test{% else %}make test{% endif %}
+```
+
+Format code:
+```bash
+{% if use_justfile %}just format{% else %}make format{% endif %}
+```

pyforge/templates/shared/env.example.jinja

@@ -0,0 +1,5 @@
+# Environment variables — copy to .env and fill in values
+# Do NOT commit .env to version control
+
+# DATABASE_URL=postgresql://user:password@localhost:5432/{{ project_name }}
+# SECRET_KEY=your-secret-key-here

pyforge/templates/shared/gitignore.jinja

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.venv/
+env/
+venv/
+ENV/
+.env
+build/
+dist/
+*.egg-info/

pyforge/templates/shared/pre-commit-config.yaml.jinja

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.5
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

pyforge/templates/shared/pyproject.toml.jinja

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ description }}"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "{{ author }}" }
+]
+{%- if license != 'none' %}
+license = { text = "{{ license }}" }
+{%- endif %}
+
+dependencies = [
+{%- if template == 'fastapi' %}
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.23.0",
+{%- elif template == 'flask' %}
+    "flask>=3.0.0",
+{%- elif template == 'cli' %}
+    "click>=8.0.0",
+{%- endif %}
+]
+
+{%- if template == 'cli' %}
+
+[project.scripts]
+{{ project_name }} = "{{ project_name }}.cli:main"
+{%- endif %}
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+{%- if template == 'fastapi' %}
+    "httpx",
+{%- endif %}
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ project_name }}"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.black]
+line-length = 88
+target-version = ['py39']
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyforge/templates/shared/requirements.txt.jinja

@@ -0,0 +1 @@
+# Add your project requirements here

pyforge/templates/shared/src/package/__init__.py.jinja

@@ -0,0 +1,3 @@
+"""
+{{ project_name }}
+"""

pyforge/utils.py

@@ -0,0 +1,65 @@
+import subprocess
+import venv
+from pathlib import Path
+from rich.console import Console
+
+console = Console()
+
+
+def is_valid_package_name(name: str) -> bool:
+    """Check if the given name is a valid Python package name."""
+    import keyword
+
+    if not name.isidentifier():
+        return False
+    # Python keywords can't be used as module names.
+    if keyword.iskeyword(name):
+        return False
+    return True
+
+
+def create_virtual_environment(project_dir: Path) -> None:
+    """Create a virtual environment in the project directory."""
+    venv_dir = project_dir / ".venv"
+    try:
+        console.print("[dim]Creating virtual environment...[/dim]")
+        venv.create(venv_dir, with_pip=True)
+    except Exception as e:
+        console.print(
+            f"[bold red]Failed to create virtual environment: {e}[/bold red]"
+        )
+
+
+def init_git_repo(project_dir: Path) -> None:
+    """Initialize a git repository and make the initial commit."""
+    try:
+        console.print("[dim]Initializing git repository...[/dim]")
+        subprocess.run(
+            ["git", "init"],
+            cwd=project_dir,
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        subprocess.run(
+            ["git", "add", "."],
+            cwd=project_dir,
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        subprocess.run(
+            ["git", "commit", "-m", "Initial commit"],
+            cwd=project_dir,
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except subprocess.CalledProcessError as e:
+        console.print(
+            f"[bold yellow]Git initialization failed. Is git installed? (Error: {e})[/bold yellow]"
+        )
+    except FileNotFoundError:
+        console.print(
+            "[bold yellow]Git executable not found. Skipping git init.[/bold yellow]"
+        )