pyforge-init 0.1.0__py3-none-any.whl

pyforge/__init__.py

@@ -0,0 +1,4 @@
+"""
+pyforge - Python Project Generator
+"""
+__version__ = "0.1.0"

pyforge/cli.py

@@ -0,0 +1,194 @@
+"""
+CLI entry point for pyforge (the `newpython` command).
+
+Precedence for values (highest → lowest):
+  1. CLI flags          (--template, --no-pre-commit, --justfile, --yes)
+  2. Config file        (~/.newpythonrc)
+  3. Interactive prompts / built-in defaults
+"""
+from __future__ import annotations
+
+import sys
+import click
+from pathlib import Path
+from rich.console import Console
+
+from pyforge.config import load_config
+from pyforge.prompts import ask_questions
+from pyforge.utils import is_valid_package_name, create_virtual_environment, init_git_repo
+from pyforge.generator import generate_project
+from pyforge.remote import is_remote_template
+
+console = Console()
+
+BUILTIN_TEMPLATES = {"basic", "cli", "fastapi", "flask"}
+
+
+def _validate_template(ctx: click.Context, param: click.Parameter, value: str) -> str:
+    """Click callback that validates both built-in names and gh: strings."""
+    if value in BUILTIN_TEMPLATES or is_remote_template(value):
+        return value
+    raise click.BadParameter(
+        f"'{value}' is not a built-in template (basic, cli, fastapi, flask) "
+        "and does not start with 'gh:'. "
+        "Use --template basic or --template gh:username/repo."
+    )
+
+
+@click.command()
+@click.argument("project_name")
+@click.option(
+    "--template",
+    default="basic",
+    show_default=True,
+    callback=_validate_template,
+    is_eager=True,
+    help=(
+        "Project template. Built-ins: basic, cli, fastapi, flask. "
+        "Remote: gh:username/repo or gh:username/repo@ref."
+    ),
+)
+@click.option(
+    "--no-pre-commit",
+    "no_pre_commit",
+    is_flag=True,
+    default=False,
+    help="Skip generating .pre-commit-config.yaml.",
+)
+@click.option(
+    "--justfile",
+    is_flag=True,
+    default=False,
+    help="Generate a Justfile instead of a Makefile.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "accept_defaults",
+    is_flag=True,
+    default=False,
+    help="Accept all defaults — skip interactive prompts (useful for CI/scripting).",
+)
+def main(
+    project_name: str,
+    template: str,
+    no_pre_commit: bool,
+    justfile: bool,
+    accept_defaults: bool,
+) -> None:
+    """✨ Scaffold a new Python project."""
+
+    # ── Validate project name ─────────────────────────────────────────────────
+    if not is_valid_package_name(project_name):
+        console.print(
+            f"[bold red]Error: '{project_name}' is not a valid Python package name.\n"
+            "Package names must be valid Python identifiers (letters, digits, underscores; "
+            "no hyphens or spaces).[/bold red]"
+        )
+        sys.exit(1)
+
+    project_dir = Path.cwd() / project_name
+    if project_dir.exists():
+        console.print(
+            f"[bold red]Error: Directory '{project_dir}' already exists.[/bold red]"
+        )
+        sys.exit(1)
+
+    # ── Load config file defaults ─────────────────────────────────────────────
+    cfg = load_config()
+
+    # CLI flags override config-file values.
+    # (no_pre_commit and justfile are False by default, so only override
+    #  when the user actually passed the flag on the CLI.)
+    effective_no_pre_commit = no_pre_commit or not cfg.get("pre_commit", True)
+    effective_justfile = justfile or cfg.get("justfile", False)
+
+    # Template: CLI always wins over config.
+    # (template is already validated by the click callback)
+    effective_template = template  # CLI value (default "basic" or user-supplied)
+    if template == "basic" and "template" in cfg:
+        # Only use config template when the CLI value is the pure default.
+        effective_template = cfg["template"]
+
+    # ── Collect answers ───────────────────────────────────────────────────────
+    if accept_defaults:
+        # Non-interactive: use config + built-in defaults, skip all prompts.
+        context = {
+            "project_name": project_name,
+            "description": cfg.get("description", "A new Python project"),
+            "author": cfg.get("author", "Your Name"),
+            "license": cfg.get("license", "MIT"),
+            "template": effective_template,
+            "use_pre_commit": not effective_no_pre_commit,
+            "use_justfile": effective_justfile,
+        }
+        init_venv = False
+        init_git = False
+    else:
+        # Interactive: merge config defaults into the prompts.
+        wizard_defaults = {
+            "description": cfg.get("description", "A new Python project"),
+            "author": cfg.get("author", "Your Name"),
+            "license": cfg.get("license", "MIT"),
+        }
+        try:
+            answers = ask_questions(project_name, wizard_defaults)
+        except (KeyboardInterrupt, click.exceptions.Abort):
+            console.print("\n[dim]Aborted.[/dim]")
+            sys.exit(0)
+
+        init_venv = answers.pop("init_venv", True)
+        init_git = answers.pop("init_git", True)
+
+        context = {
+            **answers,
+            "template": effective_template,
+            "use_pre_commit": not effective_no_pre_commit,
+            "use_justfile": effective_justfile,
+        }
+
+    # ── Generate project ──────────────────────────────────────────────────────
+    try:
+        generate_project(project_dir, context)
+    except Exception as e:
+        console.print(f"\n[bold red]✗ Error during project generation:[/bold red] {e}")
+        sys.exit(1)
+
+    # ── Post-generation actions ───────────────────────────────────────────────
+    if init_venv:
+        create_virtual_environment(project_dir)
+
+    if init_git:
+        init_git_repo(project_dir)
+
+    # ── Success message ───────────────────────────────────────────────────────
+    make_cmd = "just" if context["use_justfile"] else "make"
+
+    console.print(
+        f"\n[bold green]✓ Project [bold white]{project_name}[/bold white] created "
+        f"with template [bold white]{effective_template}[/bold white]![/bold green]"
+    )
+    console.print("\n[bold]Next steps:[/bold]")
+    console.print(f"  [cyan]cd {project_name}[/cyan]")
+
+    if init_venv:
+        console.print(
+            "  [cyan].venv\\Scripts\\activate[/cyan]"
+            "  [dim]# Windows[/dim]"
+        )
+        console.print(
+            "  [cyan]source .venv/bin/activate[/cyan]"
+            "  [dim]# macOS / Linux[/dim]"
+        )
+
+    console.print(f"  [cyan]{make_cmd} install[/cyan]")
+
+    if context["use_pre_commit"]:
+        console.print("  [cyan]pre-commit install[/cyan]")
+
+    console.print(f"  [cyan]{make_cmd} run[/cyan]")
+    console.print()
+
+
+if __name__ == "__main__":
+    main()

pyforge/config.py

@@ -0,0 +1,119 @@
+"""
+Config file support for pyforge.
+
+Reads defaults from ~/.newpythonrc (TOML format).
+The path can be overridden with the NEWPYTHON_CONFIG environment variable.
+
+Example ~/.newpythonrc:
+    author     = "Jane Doe"
+    license    = "MIT"
+    template   = "basic"
+    pre_commit = true
+    justfile   = false
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict
+
+
+# Use stdlib tomllib on Python 3.11+, fall back to tomli on older versions.
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:
+        tomllib = None  # type: ignore[assignment]
+
+CONFIG_ENV_VAR = "NEWPYTHON_CONFIG"
+DEFAULT_CONFIG_PATH = Path.home() / ".newpythonrc"
+
+# Recognised keys and their expected types for validation.
+KNOWN_KEYS: Dict[str, type] = {
+    "author": str,
+    "license": str,
+    "template": str,
+    "pre_commit": bool,
+    "justfile": bool,
+}
+
+VALID_LICENSES = {"MIT", "Apache-2.0", "none"}
+BUILTIN_TEMPLATES = {"basic", "cli", "fastapi", "flask"}
+
+
+def _config_path() -> Path:
+    """Return the config file path, respecting the env-var override."""
+    env_override = os.environ.get(CONFIG_ENV_VAR)
+    if env_override:
+        return Path(env_override).expanduser()
+    return DEFAULT_CONFIG_PATH
+
+
+def load_config() -> Dict[str, Any]:
+    """
+    Load defaults from ~/.newpythonrc.
+
+    Returns an empty dict if the file does not exist or tomllib is unavailable.
+    Prints a warning and returns an empty dict on parse errors (never crashes).
+    """
+    if tomllib is None:
+        # tomli not installed and Python < 3.11 — gracefully degrade.
+        return {}
+
+    path = _config_path()
+    if not path.exists():
+        return {}
+
+    try:
+        with open(path, "rb") as fh:
+            raw = tomllib.load(fh)
+    except Exception as exc:
+        from rich.console import Console
+        Console().print(
+            f"[bold yellow]⚠ Could not parse config file {path}: {exc}[/bold yellow]"
+        )
+        return {}
+
+    return _validate(raw, path)
+
+
+def _validate(raw: Dict[str, Any], path: Path) -> Dict[str, Any]:
+    """Validate and normalise the raw TOML data. Unknown/invalid keys are dropped with a warning."""
+    from rich.console import Console
+    console = Console()
+    clean: Dict[str, Any] = {}
+
+    for key, value in raw.items():
+        if key not in KNOWN_KEYS:
+            console.print(
+                f"[dim yellow]Config: ignoring unknown key '{key}' in {path}[/dim yellow]"
+            )
+            continue
+        expected_type = KNOWN_KEYS[key]
+        if not isinstance(value, expected_type):
+            console.print(
+                f"[dim yellow]Config: '{key}' should be {expected_type.__name__}, "
+                f"got {type(value).__name__} — ignoring.[/dim yellow]"
+            )
+            continue
+
+        # Domain validation
+        if key == "license" and value not in VALID_LICENSES:
+            console.print(
+                f"[dim yellow]Config: 'license' must be one of "
+                f"{sorted(VALID_LICENSES)}, got '{value}' — ignoring.[/dim yellow]"
+            )
+            continue
+        if key == "template" and value not in BUILTIN_TEMPLATES and not value.startswith("gh:"):
+            console.print(
+                f"[dim yellow]Config: 'template' '{value}' is not a built-in template "
+                f"and doesn't start with 'gh:' — ignoring.[/dim yellow]"
+            )
+            continue
+
+        clean[key] = value
+
+    return clean

pyforge/generator.py

@@ -0,0 +1,174 @@
+"""
+Project scaffolding engine for pyforge.
+
+Handles both local built-in templates (Jinja2-rendered) and remote
+GitHub templates (plain file copy via remote.fetch_and_apply).
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any, Dict
+
+from jinja2 import Environment, FileSystemLoader
+
+from pyforge.remote import is_remote_template, fetch_and_apply
+
+
+def get_templates_dir() -> Path:
+    """Return the absolute path to the built-in templates directory."""
+    return Path(__file__).parent / "templates"
+
+
+def render_template(
+    env: Environment,
+    template_name: str,
+    context: Dict[str, Any],
+    output_path: Path,
+) -> None:
+    """Render a single Jinja2 template and write it to *output_path*."""
+    # Jinja2 FileSystemLoader expects forward slashes on all platforms.
+    template_name_posix = template_name.replace("\\", "/")
+    template = env.get_template(template_name_posix)
+    content = template.render(**context)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def generate_project(
+    project_path: Path,
+    context: Dict[str, Any],
+) -> None:
+    """
+    Generate the project files at *project_path* using *context*.
+
+    Dispatches to the remote path when the template string starts with
+    ``gh:``; otherwise renders local Jinja2 templates.
+    """
+    template_type = context.get("template", "basic")
+
+    # ── Remote GitHub template ────────────────────────────────────────────────
+    if is_remote_template(template_type):
+        project_path.mkdir(parents=True, exist_ok=True)
+        try:
+            fetch_and_apply(template_type, project_path)
+        except Exception:
+            if project_path.exists():
+                shutil.rmtree(project_path)
+            raise
+        return
+
+    # ── Local Jinja2 template ─────────────────────────────────────────────────
+    use_pre_commit = context.get("use_pre_commit", True)
+    use_justfile = context.get("use_justfile", False)
+    templates_dir = get_templates_dir()
+
+    project_path.mkdir(parents=True, exist_ok=True)
+
+    # Load templates: template-specific folder takes priority over shared.
+    env = Environment(
+        loader=FileSystemLoader(
+            [
+                str(templates_dir / template_type),
+                str(templates_dir / "shared"),
+            ]
+        ),
+        keep_trailing_newline=True,
+    )
+
+    try:
+        # ── Shared files ──────────────────────────────────────────────────────
+        render_template(
+            env, "pyproject.toml.jinja", context, project_path / "pyproject.toml"
+        )
+        render_template(
+            env, "gitignore.jinja", context, project_path / ".gitignore"
+        )
+        render_template(
+            env, "env.example.jinja", context, project_path / ".env.example"
+        )
+
+        if use_pre_commit:
+            render_template(
+                env,
+                "pre-commit-config.yaml.jinja",
+                context,
+                project_path / ".pre-commit-config.yaml",
+            )
+
+        makefile_name = "Justfile" if use_justfile else "Makefile"
+        makefile_template = "Justfile.jinja" if use_justfile else "Makefile.jinja"
+        render_template(
+            env, makefile_template, context, project_path / makefile_name
+        )
+
+        # ── Template-specific files ───────────────────────────────────────────
+        render_template(
+            env, "README.md.jinja", context, project_path / "README.md"
+        )
+        render_template(
+            env,
+            "requirements.txt.jinja",
+            context,
+            project_path / "requirements.txt",
+        )
+
+        package_dir = project_path / "src" / context["project_name"]
+        render_template(
+            env,
+            "src/package/__init__.py.jinja",
+            context,
+            package_dir / "__init__.py",
+        )
+
+        if template_type == "cli":
+            render_template(
+                env,
+                "src/package/__main__.py.jinja",
+                context,
+                package_dir / "__main__.py",
+            )
+            render_template(
+                env, "src/package/cli.py.jinja", context, package_dir / "cli.py"
+            )
+            render_template(
+                env,
+                "tests/test_cli.py.jinja",
+                context,
+                project_path / "tests" / "test_cli.py",
+            )
+        elif template_type == "fastapi":
+            render_template(
+                env, "src/package/main.py.jinja", context, package_dir / "main.py"
+            )
+            render_template(
+                env,
+                "tests/test_main.py.jinja",
+                context,
+                project_path / "tests" / "test_main.py",
+            )
+        elif template_type == "flask":
+            render_template(
+                env, "src/package/app.py.jinja", context, package_dir / "app.py"
+            )
+            render_template(
+                env,
+                "tests/test_app.py.jinja",
+                context,
+                project_path / "tests" / "test_app.py",
+            )
+        else:  # basic
+            render_template(
+                env,
+                "tests/test_main.py.jinja",
+                context,
+                project_path / "tests" / "test_main.py",
+            )
+
+    except Exception:
+        # Clean up any partially-created project directory on failure.
+        if project_path.exists():
+            shutil.rmtree(project_path)
+        raise

pyforge/prompts.py

@@ -0,0 +1,167 @@
+"""
+Interactive TUI prompts for pyforge using questionary.
+
+Provides a beautiful, npm-create-vite-style wizard for collecting project
+configuration. Falls back to click.prompt/confirm when questionary is not
+available (e.g., non-interactive/CI environments).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+console = Console()
+
+BUILTIN_TEMPLATES = ["basic", "cli", "fastapi", "flask"]
+LICENSES = ["MIT", "Apache-2.0", "none"]
+
+
+def _print_header(project_name: str) -> None:
+    """Print the styled welcome banner."""
+    title = Text("✨  newpython", style="bold cyan")
+    subtitle = Text(f"Scaffolding project: {project_name}", style="dim")
+    combined = Text.assemble(title, "\n", subtitle)
+    console.print(Panel(combined, border_style="cyan", padding=(0, 2)))
+    console.print()
+
+
+def _is_interactive() -> bool:
+    """Return True if we are attached to a real TTY."""
+    import sys
+    return sys.stdin.isatty()
+
+
+def ask_questions(project_name: str, defaults: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Run the interactive questionary wizard (or fall back to click prompts in CI).
+
+    Args:
+        project_name: The project name already validated and accepted via CLI arg.
+        defaults: Pre-populated values from the config file.
+
+    Returns:
+        A fully populated context dict ready for the generator.
+    """
+    _print_header(project_name)
+
+    if _is_interactive():
+        return _ask_with_questionary(project_name, defaults)
+    else:
+        console.print("[dim]Non-interactive mode — using defaults.[/dim]")
+        return _ask_with_click(project_name, defaults)
+
+
+def _ask_with_questionary(project_name: str, defaults: Dict[str, Any]) -> Dict[str, Any]:
+    """Collect answers using questionary (full TUI)."""
+    import questionary
+    from questionary import Style
+
+    custom_style = Style([
+        ("qmark",        "fg:#5f87ff bold"),
+        ("question",     "bold"),
+        ("answer",       "fg:#5fd7ff bold"),
+        ("pointer",      "fg:#5f87ff bold"),
+        ("highlighted",  "fg:#5f87ff bold"),
+        ("selected",     "fg:#5fd7ff"),
+        ("separator",    "fg:#6c6c6c"),
+        ("instruction",  "fg:#6c6c6c italic"),
+    ])
+
+    # ── Description ───────────────────────────────────────────────────────────
+    description = questionary.text(
+        "Project description:",
+        default=defaults.get("description", "A new Python project"),
+        style=custom_style,
+    ).ask()
+    if description is None:  # user hit Ctrl-C
+        raise KeyboardInterrupt
+
+    # ── Author ─────────────────────────────────────────────────────────────────
+    author = questionary.text(
+        "Author name:",
+        default=defaults.get("author", "Your Name"),
+        style=custom_style,
+    ).ask()
+    if author is None:
+        raise KeyboardInterrupt
+
+    # ── License ────────────────────────────────────────────────────────────────
+    license_default = defaults.get("license", "MIT")
+    license_type = questionary.select(
+        "License:",
+        choices=LICENSES,
+        default=license_default if license_default in LICENSES else "MIT",
+        style=custom_style,
+    ).ask()
+    if license_type is None:
+        raise KeyboardInterrupt
+
+    # ── Virtual environment ────────────────────────────────────────────────────
+    init_venv = questionary.confirm(
+        "Initialize a virtual environment (.venv)?",
+        default=True,
+        style=custom_style,
+    ).ask()
+    if init_venv is None:
+        raise KeyboardInterrupt
+
+    # ── Git ────────────────────────────────────────────────────────────────────
+    init_git = questionary.confirm(
+        "Initialize a git repository?",
+        default=True,
+        style=custom_style,
+    ).ask()
+    if init_git is None:
+        raise KeyboardInterrupt
+
+    console.print()
+    return _build_context(project_name, defaults, description, author,
+                          license_type, init_venv, init_git)
+
+
+def _ask_with_click(project_name: str, defaults: Dict[str, Any]) -> Dict[str, Any]:
+    """Fallback: collect answers using plain click prompts (CI / non-TTY)."""
+    import click
+
+    description = click.prompt(
+        "Project description",
+        default=defaults.get("description", "A new Python project"),
+    )
+    author = click.prompt(
+        "Author name",
+        default=defaults.get("author", "Your Name"),
+    )
+    license_type = click.prompt(
+        "License",
+        type=click.Choice(LICENSES),
+        default=defaults.get("license", "MIT"),
+    )
+    init_venv = click.confirm("Initialize virtual environment?", default=True)
+    init_git = click.confirm("Initialize git repository?", default=True)
+
+    return _build_context(project_name, defaults, description, author,
+                          license_type, init_venv, init_git)
+
+
+def _build_context(
+    project_name: str,
+    defaults: Dict[str, Any],
+    description: str,
+    author: str,
+    license_type: str,
+    init_venv: bool,
+    init_git: bool,
+) -> Dict[str, Any]:
+    """Assemble the final context dict passed to the generator and actions."""
+    return {
+        "project_name": project_name,
+        "description": description,
+        "author": author,
+        "license": license_type,
+        # template and tool flags come from CLI / config, not the wizard
+        "init_venv": init_venv,
+        "init_git": init_git,
+    }