tses 0.1.0__tar.gz

tses-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[dev]
+
+      - name: Run tests
+        run: python -m pytest

tses-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

tses-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+.coverage
+htmlcov/

tses-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 TSES.
+All rights reserved.
+
+This repository and its contents are proprietary to TSES.
+No permission is granted to use, copy, modify, distribute, sublicense,
+or create derivative works from this software except by prior written
+agreement with TSES.

tses-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: tses
+Version: 0.1.0
+Summary: TSES project scaffold generator for Django and FastAPI services.
+Author: TSES
+License: Proprietary
+License-File: LICENSE
+Keywords: cli,django,fastapi,scaffold,tses
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2.post1; extra == 'dev'
+Requires-Dist: pytest>=8.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TSES
+
+`tses` is the TSES scaffold generator CLI for bootstrapping curated Django and FastAPI service projects.
+
+## Install
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+For end users after publishing:
+
+```bash
+pip install tses
+```
+
+A `pipx install tses` workflow can also be used for isolated CLI installs.
+
+## Usage
+
+Generate a Django scaffold into a new directory:
+
+```bash
+tses startproject my-django-service -f django
+```
+
+Generate a FastAPI scaffold into the current directory:
+
+```bash
+tses startproject . -f fastapi --force
+```
+
+Available options:
+
+- `-f`, `--framework`: required framework choice, `django` or `fastapi`
+- `--force`: overwrite scaffold-managed files in a non-empty target directory
+- `--dry-run`: print planned file actions without writing files
+- `--verbose`: print per-file actions during generation
+- `--version`: print the installed `tses` version
+
+## Development
+
+Scaffold snapshots are vendored into `src/tses/templates`.
+Use the sync script to refresh them from the scaffold repos:
+
+```bash
+python tools/sync_scaffolds.py
+```
+
+Default source repos:
+
+- `/home/mike/django-scaffold`
+- `/home/mike/fastapi-scaffold`
+
+Before the first public release, confirm that the package name `tses` is available on the intended package index.

tses-0.1.0/README.md

@@ -0,0 +1,57 @@
+# TSES
+
+`tses` is the TSES scaffold generator CLI for bootstrapping curated Django and FastAPI service projects.
+
+## Install
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+For end users after publishing:
+
+```bash
+pip install tses
+```
+
+A `pipx install tses` workflow can also be used for isolated CLI installs.
+
+## Usage
+
+Generate a Django scaffold into a new directory:
+
+```bash
+tses startproject my-django-service -f django
+```
+
+Generate a FastAPI scaffold into the current directory:
+
+```bash
+tses startproject . -f fastapi --force
+```
+
+Available options:
+
+- `-f`, `--framework`: required framework choice, `django` or `fastapi`
+- `--force`: overwrite scaffold-managed files in a non-empty target directory
+- `--dry-run`: print planned file actions without writing files
+- `--verbose`: print per-file actions during generation
+- `--version`: print the installed `tses` version
+
+## Development
+
+Scaffold snapshots are vendored into `src/tses/templates`.
+Use the sync script to refresh them from the scaffold repos:
+
+```bash
+python tools/sync_scaffolds.py
+```
+
+Default source repos:
+
+- `/home/mike/django-scaffold`
+- `/home/mike/fastapi-scaffold`
+
+Before the first public release, confirm that the package name `tses` is available on the intended package index.

tses-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tses"
+version = "0.1.0"
+description = "TSES project scaffold generator for Django and FastAPI services."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [
+  { name = "TSES" },
+]
+keywords = ["tses", "scaffold", "django", "fastapi", "cli"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2.post1",
+  "pytest>=8.4.0",
+]
+
+[project.scripts]
+tses = "tses.cli:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tses"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/tses",
+  "/README.md",
+  "/LICENSE",
+  "/tools",
+  "/tests",
+  "/.github/workflows",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

tses-0.1.0/src/tses/__init__.py

@@ -0,0 +1,3 @@
+"""TSES scaffold generator package."""
+
+__version__ = "0.1.0"

tses-0.1.0/src/tses/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for `python -m tses`."""
+
+from tses.cli import run
+
+
+if __name__ == "__main__":
+    run()

tses-0.1.0/src/tses/cli.py

@@ -0,0 +1,79 @@
+"""Command-line interface for the TSES scaffold generator."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tses import __version__
+from tses.commands.startproject import handle_startproject
+from tses.core.errors import TsesError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level CLI parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="tses",
+        description="Generate curated Django or FastAPI project scaffolds.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"tses {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    startproject_parser = subparsers.add_parser(
+        "startproject",
+        help="Generate a project scaffold into the target directory.",
+    )
+    startproject_parser.add_argument(
+        "target",
+        help="Target directory to generate into. Use '.' for the current directory.",
+    )
+    startproject_parser.add_argument(
+        "-f",
+        "--framework",
+        required=True,
+        choices=("django", "fastapi"),
+        help="Framework scaffold to generate.",
+    )
+    startproject_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite scaffold-managed files in a non-empty target directory.",
+    )
+    startproject_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print planned actions without writing files.",
+    )
+    startproject_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print per-file actions during generation.",
+    )
+    startproject_parser.set_defaults(handler=handle_startproject)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return an exit code."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        return args.handler(args)
+    except TsesError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def run() -> None:
+    """Run the CLI as a console-script entry point."""
+
+    raise SystemExit(main())

tses-0.1.0/src/tses/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command handlers for TSES."""

tses-0.1.0/src/tses/commands/startproject.py

@@ -0,0 +1,75 @@
+"""Implementation of the `tses startproject` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tses.core.filesystem import PlannedAction
+from tses.core.generator import GenerationResult, generate_scaffold
+
+
+def handle_startproject(args) -> int:
+    """Generate the requested scaffold and print user-facing output."""
+
+    result = generate_scaffold(
+        framework=args.framework,
+        target=Path(args.target),
+        force=args.force,
+        dry_run=args.dry_run,
+    )
+
+    if args.dry_run:
+        print(f"Dry run for {result.framework} scaffold")
+        print(f"Target: {result.target_dir}")
+        for action in result.actions:
+            _print_action(action, prefix="Would")
+        print(
+            f"Would create {result.created_count} files and overwrite "
+            f"{result.overwritten_count} files."
+        )
+        return 0
+
+    if args.verbose:
+        for action in result.actions:
+            _print_action(action)
+
+    print("Project generated successfully.")
+    print(f"Framework: {result.framework}")
+    print(f"Target: {result.target_dir}")
+    print(f"Project name: {result.metadata.project_name}")
+    print(f"Force mode: {'yes' if args.force else 'no'}")
+    print(f"Created files: {result.created_count}")
+    print(f"Overwritten files: {result.overwritten_count}")
+    print("Next steps:")
+    for step in _build_next_steps(result):
+        print(f"  {step}")
+    return 0
+
+
+def _print_action(action: PlannedAction, prefix: str | None = None) -> None:
+    """Print one planned or completed file action."""
+
+    verb = action.kind if prefix is None else f"{prefix} {action.kind}"
+    print(f"{verb:>16}  {action.relative_path.as_posix()}")
+
+
+def _build_next_steps(result: GenerationResult) -> list[str]:
+    """Return framework-specific follow-up steps for the user."""
+
+    steps: list[str] = []
+    if result.original_target != Path("."):
+        steps.append(f"cd {result.target_dir}")
+
+    env_example = result.target_dir / ".env.example"
+    env_file = result.target_dir / ".env"
+    if env_example.exists() and not env_file.exists():
+        steps.append("cp .env.example .env")
+
+    if result.framework == "django":
+        steps.append("docker compose up --build")
+        steps.append("python manage.py migrate")
+    else:
+        steps.append("docker compose up --build")
+        steps.append("alembic upgrade head")
+
+    return steps

tses-0.1.0/src/tses/core/__init__.py

@@ -0,0 +1 @@
+"""Core generation utilities for TSES."""

tses-0.1.0/src/tses/core/errors.py

@@ -0,0 +1,17 @@
+"""Custom exceptions raised by the TSES scaffold generator."""
+
+
+class TsesError(Exception):
+    """Base exception for user-facing generator errors."""
+
+
+class UnsupportedFrameworkError(TsesError):
+    """Raised when a framework choice is not supported."""
+
+
+class UnsafeTargetError(TsesError):
+    """Raised when generation would write into an unsafe target directory."""
+
+
+class GenerationError(TsesError):
+    """Raised when file generation cannot complete safely."""

tses-0.1.0/src/tses/core/filesystem.py

@@ -0,0 +1,91 @@
+"""Filesystem planning helpers for scaffold generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+from importlib.abc import Traversable
+
+from tses.core.errors import GenerationError, UnsafeTargetError
+
+
+@dataclass(frozen=True)
+class PlannedAction:
+    """One file action required to realize a scaffold generation request."""
+
+    kind: str
+    relative_path: Path
+    source: Traversable
+    destination: Path
+
+
+def prepare_target_directory(target_dir: Path, *, force: bool, dry_run: bool) -> None:
+    """Validate the target directory and create it when appropriate."""
+
+    if target_dir.exists() and not target_dir.is_dir():
+        raise UnsafeTargetError(f"Target path is not a directory: {target_dir}")
+
+    if target_dir.exists():
+        if any(target_dir.iterdir()) and not force:
+            raise UnsafeTargetError(
+                "Target directory is not empty. Re-run with --force to overwrite "
+                "scaffold-managed files."
+            )
+        return
+
+    if not dry_run:
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+
+def plan_actions(template_root: Traversable, target_dir: Path) -> list[PlannedAction]:
+    """Plan the file actions required to copy a scaffold into the target."""
+
+    actions: list[PlannedAction] = []
+    for source, relative_path in iter_template_files(template_root):
+        destination = target_dir / relative_path
+        _validate_parent_paths(target_dir=target_dir, destination=destination)
+
+        if destination.exists() and destination.is_dir():
+            raise GenerationError(
+                f"Cannot overwrite directory with file: {destination}"
+            )
+
+        action_kind = "overwrite" if destination.exists() else "create"
+        actions.append(
+            PlannedAction(
+                kind=action_kind,
+                relative_path=relative_path,
+                source=source,
+                destination=destination,
+            )
+        )
+
+    return actions
+
+
+def iter_template_files(
+    root: Traversable,
+    relative_path: Path = Path(),
+) -> Iterator[tuple[Traversable, Path]]:
+    """Yield every file under a template root with a stable relative path."""
+
+    for child in sorted(root.iterdir(), key=lambda entry: entry.name):
+        child_relative_path = relative_path / child.name
+        if child.is_dir():
+            yield from iter_template_files(child, child_relative_path)
+        elif child.is_file():
+            yield child, child_relative_path
+
+
+def _validate_parent_paths(*, target_dir: Path, destination: Path) -> None:
+    """Ensure no parent segment that should be a directory is already a file."""
+
+    current = destination.parent
+    while current != target_dir.parent:
+        if current.exists() and not current.is_dir():
+            raise GenerationError(f"Path segment is a file, not a directory: {current}")
+        if current == target_dir:
+            break
+        current = current.parent

tses-0.1.0/src/tses/core/generator.py

@@ -0,0 +1,90 @@
+"""High-level scaffold generation orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from importlib.abc import Traversable
+from pathlib import Path
+
+from tses.core.errors import GenerationError, UnsupportedFrameworkError
+from tses.core.filesystem import PlannedAction, plan_actions, prepare_target_directory
+from tses.core.metadata import GenerationMetadata, build_generation_metadata
+from tses.core.renderer import apply_action
+
+
+SUPPORTED_FRAMEWORKS = {"django", "fastapi"}
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    """Summary of one scaffold generation run."""
+
+    framework: str
+    original_target: Path
+    target_dir: Path
+    metadata: GenerationMetadata
+    actions: list[PlannedAction]
+
+    @property
+    def created_count(self) -> int:
+        """Return the number of created files."""
+
+        return sum(1 for action in self.actions if action.kind == "create")
+
+    @property
+    def overwritten_count(self) -> int:
+        """Return the number of overwritten files."""
+
+        return sum(1 for action in self.actions if action.kind == "overwrite")
+
+
+def generate_scaffold(
+    *,
+    framework: str,
+    target: Path,
+    force: bool = False,
+    dry_run: bool = False,
+) -> GenerationResult:
+    """Generate a vendored framework scaffold into the target directory."""
+
+    normalized_framework = framework.strip().lower()
+    template_root = get_template_root(normalized_framework)
+
+    target_dir = target.expanduser().resolve()
+    metadata = build_generation_metadata(
+        framework=normalized_framework,
+        target_dir=target_dir,
+    )
+
+    prepare_target_directory(target_dir, force=force, dry_run=dry_run)
+    actions = plan_actions(template_root, target_dir)
+
+    if not dry_run:
+        for action in actions:
+            apply_action(action, metadata)
+
+    return GenerationResult(
+        framework=normalized_framework,
+        original_target=target,
+        target_dir=target_dir,
+        metadata=metadata,
+        actions=actions,
+    )
+
+
+def get_template_root(framework: str) -> Traversable:
+    """Return the vendored template root for a supported framework."""
+
+    if framework not in SUPPORTED_FRAMEWORKS:
+        raise UnsupportedFrameworkError(
+            f"Unsupported framework '{framework}'. Expected one of: django, fastapi."
+        )
+
+    template_root = resources.files("tses.templates").joinpath(framework)
+    if not template_root.exists() or not template_root.is_dir():
+        raise GenerationError(
+            f"Vendored template for framework '{framework}' is missing. "
+            "Run tools/sync_scaffolds.py to refresh scaffold snapshots."
+        )
+    return template_root