pyoas 0.1.0__tar.gz

pyoas-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.3
+Name: pyoas
+Version: 0.1.0
+Summary: Generate Pydantic v2 models and FastAPI routers from OpenAPI 3.0/3.1 specs
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonref>=1.1
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruff>=0.4
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=3.0
+Requires-Dist: polyfactory>=2.0
+Requires-Dist: pyoas[fastapi,claude] ; extra == 'all'
+Requires-Dist: fastapi>=0.110 ; extra == 'fastapi'
+Requires-Python: >=3.12
+Provides-Extra: all
+Provides-Extra: claude
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# pyoas
+
+Generate Pydantic v2 models and FastAPI routers from an OpenAPI spec. Organized as a uv workspace with independent, installable packages.
+
+## Packages
+
+| Package | Purpose |
+|---|---|
+| `pyoas` | Foundation: spec loading, ref resolution, tag extraction, Jinja2 rendering, CLI |
+| `pyoas` | Pydantic v2 model generation from OpenAPI schemas |
+| `pyoas[fastapi]` | FastAPI router + service stub generation + test scaffolding |
+| `pyoas[claude]` | Claude Code skill generation (optional) |
+
+`pyoas[fastapi]` depends on `pyoas`; both depend on `pyoas`. `pyoas[claude]` depends on `pyoas`.
+
+## Quick start
+
+```shell
+# Install
+uv add pyoas[fastapi]
+
+# Create a minimal config
+cat > pyoas.yaml << 'EOF'
+spec: openapi.yaml
+output:
+  models: src/generated/models
+  routers: src/generated/routers
+EOF
+
+# Generate Pydantic models and FastAPI routers
+uv run pyoas generate
+
+# Optionally scaffold service stubs and test files
+uv run pyoas scaffold services
+```
+
+A more complete config with all optional features:
+
+```yaml
+spec: openapi.yaml
+output:
+  models: src/generated/models
+  routers: src/generated/routers
+services:
+  generate: true
+  output: src/services
+  import_path: myapp.services  # Python import path for service module
+tests:
+  generate: true
+  output: tests/generated
+  not_found_exception: "HTTPException(status_code=404, detail='Not found')"
+skills:
+  generate: true  # requires pyoas[claude]
+```
+
+Then:
+
+```shell
+uv run pyoas generate   # models + routers + service stubs + tests + skills
+```
+
+## Configuration reference (`pyoas.yaml`)
+
+### `spec`
+
+Path to the OpenAPI 3.0/3.1 spec file (YAML or JSON). Resolved relative to the config file. **Required.**
+
+### `output`
+
+| Key | Default | Description |
+|---|---|---|
+| `models` | `src/generated/models` | Output directory for generated model files |
+| `routers` | `src/generated/routers` | Output directory for generated router files |
+| `models_import` | _(derived)_ | Python import path for models; derived from `models` path if omitted |
+| `routers_import` | _(derived)_ | Python import path for routers; derived from `routers` path if omitted |
+| `source_root` | `src` | Filesystem prefix stripped when deriving Python import paths |
+
+### `default_tag`
+
+Default: `"default"`. Operations with no tag are grouped under this name.
+
+### `model_config`
+
+| Key | Default | Description |
+|---|---|---|
+| `extra` | `"ignore"` | Pydantic `extra` setting for response/shared models |
+| `request_extra` | `"forbid"` | Pydantic `extra` setting for request-only models |
+| `frozen` | `false` | Makes generated models immutable |
+| `populate_by_name` | `true` | Allow populating fields by Python name as well as alias |
+
+### `fields`
+
+| Key | Default | Description |
+|---|---|---|
+| `snake_case` | `true` | Convert camelCase field names to snake_case with an alias |
+| `enums_as_literals` | `true` | Render small enums as `Literal[...]` instead of `Enum` subclasses |
+
+### `format`
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Run `ruff format` on generated files after writing |
+
+### `templates`
+
+| Key | Default | Description |
+|---|---|---|
+| `models` | `null` | Path to a directory of custom Jinja2 templates overriding model templates |
+| `routers` | `null` | Path to a directory of custom Jinja2 templates overriding router templates |
+
+### `services`
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Scaffold service stub files |
+| `output` | `src/services` | Output directory for service files |
+| `overwrite` | `false` | Overwrite existing service files on re-run |
+| `import_path` | `""` | Python import path used by routers to import the service (e.g. `myapp.services`) |
+
+### `tests`
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Scaffold pytest test stub files |
+| `output` | `tests/generated` | Output directory for test files |
+| `overwrite` | `false` | Overwrite existing test files on re-run (default: append new test classes only) |
+| `not_found_exception` | `null` | Exception expression used in `test_not_found` stubs (e.g. `HTTPException(status_code=404)`) |
+
+### `skills`
+
+Requires `pyoas[claude]` to be installed.
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Generate Claude Code skill files |
+| `output` | `.claude/commands` | Output directory for skill files |
+| `overwrite` | `false` | Overwrite existing skill files on re-run |
+
+## Generated output
+
+### Models (`pyoas`)
+
+One file per tag: `{models_output}/{tag}/models.py`. Schemas referenced by multiple tags go to `{models_output}/shared/models.py`.
+
+```
+src/generated/models/
+  __init__.py
+  pets/
+    models.py      # Pet, PetCreate, PetList, ...
+  shared/
+    models.py      # schemas used by more than one tag
+```
+
+### Routers (`pyoas[fastapi]`)
+
+One file per tag: `{routers_output}/{tag}/router.py`. An `__init__.py` at the root re-exports all routers.
+
+```
+src/generated/routers/
+  __init__.py      # from .pets import router as pets_router; ...
+  pets/
+    router.py      # APIRouter with typed endpoint stubs
+```
+
+### Service stubs
+
+One file per tag: `{services_output}/{tag}.py`. Scaffolded once; never overwritten by default.
+
+```
+src/services/
+  pets.py          # PetsService class with async method stubs
+```
+
+### Test scaffolding
+
+One test file per tag plus a shared `conftest.py` with model factories.
+
+```
+tests/generated/
+  conftest.py      # make_pet(), make_pet_list(), ...
+  test_pets.py     # TestListPets, TestCreatePet, TestGetPet, ...
+```
+
+Each test class covers one endpoint and includes:
+- `test_endpoint_exists` — verifies the route returns something other than 404/405
+- Validation tests for required fields, numeric bounds, string constraints, enum violations
+- `test_not_found` — verifies 404 when the service raises the configured exception
+- `test_success` — happy-path stub (auto-implemented for GET/DELETE, stubbed for others)
+
+## CLI reference
+
+```shell
+pyoas models        # generate Pydantic models only
+pyoas fastapi       # generate FastAPI routers only
+pyoas generate      # generate models + routers (+ services/tests/skills if configured)
+pyoas scaffold services  # scaffold service stubs (skips existing files)
+```
+
+All commands accept:
+- `--config PATH` — path to config file (default: `pyoas.yaml`)
+- `--tags TAG1,TAG2` — limit generation to specific tags
+- `--clean` — purge output directory before generating
+
+## Claude Code integration (`pyoas[claude]`)
+
+Install `pyoas[claude]` and set `skills.generate: true` in your config. Running `pyoas generate` will write Claude Code skill files to `.claude/commands/`:
+
+| Skill | Invocation | Purpose |
+|---|---|---|
+| `implement-tests.md` | `/implement-tests tests/generated/test_pets.py` | Implement all `pytest.skip("implement me")` stubs in a test file |
+| `add-test-case.md` | `/add-test-case tests/generated/test_pets.py "scenario"` | Add a new test method for the described scenario |
+| `review-generated.md` | `/review-generated` | Cross-reference generated code against the OpenAPI spec and flag issues |
+
+## Development
+
+```shell
+# Install all workspace packages in editable mode
+uv sync --all-packages
+
+# Run all tests
+uv run pytest
+
+# Run tests for a single package
+uv run pytest packages/pyoas[fastapi]/
+
+# Update snapshots
+uv run pytest packages/pyoas[fastapi]/ --snapshot-update
+
+# Lint and type-check
+uv run ruff check packages/
+uv run mypy packages/
+```

pyoas-0.1.0/README.md

@@ -0,0 +1,232 @@
+# pyoas
+
+Generate Pydantic v2 models and FastAPI routers from an OpenAPI spec. Organized as a uv workspace with independent, installable packages.
+
+## Packages
+
+| Package | Purpose |
+|---|---|
+| `pyoas` | Foundation: spec loading, ref resolution, tag extraction, Jinja2 rendering, CLI |
+| `pyoas` | Pydantic v2 model generation from OpenAPI schemas |
+| `pyoas[fastapi]` | FastAPI router + service stub generation + test scaffolding |
+| `pyoas[claude]` | Claude Code skill generation (optional) |
+
+`pyoas[fastapi]` depends on `pyoas`; both depend on `pyoas`. `pyoas[claude]` depends on `pyoas`.
+
+## Quick start
+
+```shell
+# Install
+uv add pyoas[fastapi]
+
+# Create a minimal config
+cat > pyoas.yaml << 'EOF'
+spec: openapi.yaml
+output:
+  models: src/generated/models
+  routers: src/generated/routers
+EOF
+
+# Generate Pydantic models and FastAPI routers
+uv run pyoas generate
+
+# Optionally scaffold service stubs and test files
+uv run pyoas scaffold services
+```
+
+A more complete config with all optional features:
+
+```yaml
+spec: openapi.yaml
+output:
+  models: src/generated/models
+  routers: src/generated/routers
+services:
+  generate: true
+  output: src/services
+  import_path: myapp.services  # Python import path for service module
+tests:
+  generate: true
+  output: tests/generated
+  not_found_exception: "HTTPException(status_code=404, detail='Not found')"
+skills:
+  generate: true  # requires pyoas[claude]
+```
+
+Then:
+
+```shell
+uv run pyoas generate   # models + routers + service stubs + tests + skills
+```
+
+## Configuration reference (`pyoas.yaml`)
+
+### `spec`
+
+Path to the OpenAPI 3.0/3.1 spec file (YAML or JSON). Resolved relative to the config file. **Required.**
+
+### `output`
+
+| Key | Default | Description |
+|---|---|---|
+| `models` | `src/generated/models` | Output directory for generated model files |
+| `routers` | `src/generated/routers` | Output directory for generated router files |
+| `models_import` | _(derived)_ | Python import path for models; derived from `models` path if omitted |
+| `routers_import` | _(derived)_ | Python import path for routers; derived from `routers` path if omitted |
+| `source_root` | `src` | Filesystem prefix stripped when deriving Python import paths |
+
+### `default_tag`
+
+Default: `"default"`. Operations with no tag are grouped under this name.
+
+### `model_config`
+
+| Key | Default | Description |
+|---|---|---|
+| `extra` | `"ignore"` | Pydantic `extra` setting for response/shared models |
+| `request_extra` | `"forbid"` | Pydantic `extra` setting for request-only models |
+| `frozen` | `false` | Makes generated models immutable |
+| `populate_by_name` | `true` | Allow populating fields by Python name as well as alias |
+
+### `fields`
+
+| Key | Default | Description |
+|---|---|---|
+| `snake_case` | `true` | Convert camelCase field names to snake_case with an alias |
+| `enums_as_literals` | `true` | Render small enums as `Literal[...]` instead of `Enum` subclasses |
+
+### `format`
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Run `ruff format` on generated files after writing |
+
+### `templates`
+
+| Key | Default | Description |
+|---|---|---|
+| `models` | `null` | Path to a directory of custom Jinja2 templates overriding model templates |
+| `routers` | `null` | Path to a directory of custom Jinja2 templates overriding router templates |
+
+### `services`
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Scaffold service stub files |
+| `output` | `src/services` | Output directory for service files |
+| `overwrite` | `false` | Overwrite existing service files on re-run |
+| `import_path` | `""` | Python import path used by routers to import the service (e.g. `myapp.services`) |
+
+### `tests`
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Scaffold pytest test stub files |
+| `output` | `tests/generated` | Output directory for test files |
+| `overwrite` | `false` | Overwrite existing test files on re-run (default: append new test classes only) |
+| `not_found_exception` | `null` | Exception expression used in `test_not_found` stubs (e.g. `HTTPException(status_code=404)`) |
+
+### `skills`
+
+Requires `pyoas[claude]` to be installed.
+
+| Key | Default | Description |
+|---|---|---|
+| `generate` | `false` | Generate Claude Code skill files |
+| `output` | `.claude/commands` | Output directory for skill files |
+| `overwrite` | `false` | Overwrite existing skill files on re-run |
+
+## Generated output
+
+### Models (`pyoas`)
+
+One file per tag: `{models_output}/{tag}/models.py`. Schemas referenced by multiple tags go to `{models_output}/shared/models.py`.
+
+```
+src/generated/models/
+  __init__.py
+  pets/
+    models.py      # Pet, PetCreate, PetList, ...
+  shared/
+    models.py      # schemas used by more than one tag
+```
+
+### Routers (`pyoas[fastapi]`)
+
+One file per tag: `{routers_output}/{tag}/router.py`. An `__init__.py` at the root re-exports all routers.
+
+```
+src/generated/routers/
+  __init__.py      # from .pets import router as pets_router; ...
+  pets/
+    router.py      # APIRouter with typed endpoint stubs
+```
+
+### Service stubs
+
+One file per tag: `{services_output}/{tag}.py`. Scaffolded once; never overwritten by default.
+
+```
+src/services/
+  pets.py          # PetsService class with async method stubs
+```
+
+### Test scaffolding
+
+One test file per tag plus a shared `conftest.py` with model factories.
+
+```
+tests/generated/
+  conftest.py      # make_pet(), make_pet_list(), ...
+  test_pets.py     # TestListPets, TestCreatePet, TestGetPet, ...
+```
+
+Each test class covers one endpoint and includes:
+- `test_endpoint_exists` — verifies the route returns something other than 404/405
+- Validation tests for required fields, numeric bounds, string constraints, enum violations
+- `test_not_found` — verifies 404 when the service raises the configured exception
+- `test_success` — happy-path stub (auto-implemented for GET/DELETE, stubbed for others)
+
+## CLI reference
+
+```shell
+pyoas models        # generate Pydantic models only
+pyoas fastapi       # generate FastAPI routers only
+pyoas generate      # generate models + routers (+ services/tests/skills if configured)
+pyoas scaffold services  # scaffold service stubs (skips existing files)
+```
+
+All commands accept:
+- `--config PATH` — path to config file (default: `pyoas.yaml`)
+- `--tags TAG1,TAG2` — limit generation to specific tags
+- `--clean` — purge output directory before generating
+
+## Claude Code integration (`pyoas[claude]`)
+
+Install `pyoas[claude]` and set `skills.generate: true` in your config. Running `pyoas generate` will write Claude Code skill files to `.claude/commands/`:
+
+| Skill | Invocation | Purpose |
+|---|---|---|
+| `implement-tests.md` | `/implement-tests tests/generated/test_pets.py` | Implement all `pytest.skip("implement me")` stubs in a test file |
+| `add-test-case.md` | `/add-test-case tests/generated/test_pets.py "scenario"` | Add a new test method for the described scenario |
+| `review-generated.md` | `/review-generated` | Cross-reference generated code against the OpenAPI spec and flag issues |
+
+## Development
+
+```shell
+# Install all workspace packages in editable mode
+uv sync --all-packages
+
+# Run all tests
+uv run pytest
+
+# Run tests for a single package
+uv run pytest packages/pyoas[fastapi]/
+
+# Update snapshots
+uv run pytest packages/pyoas[fastapi]/ --snapshot-update
+
+# Lint and type-check
+uv run ruff check packages/
+uv run mypy packages/
+```

pyoas-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "pyoas"
+version = "0.1.0"
+description = "Generate Pydantic v2 models and FastAPI routers from OpenAPI 3.0/3.1 specs"
+requires-python = ">=3.12"
+readme = "README.md"
+dependencies = [
+    "jinja2>=3.1",
+    "jsonref>=1.1",
+    "openapi-spec-validator>=0.7",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "ruff>=0.4",
+    "typer>=0.12",
+    "watchdog>=3.0",
+    "polyfactory>=2.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+claude = []
+all = ["pyoas[fastapi,claude]"]
+
+[project.scripts]
+pyoas = "pyoas.core.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pyoas"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "syrupy>=4.0",
+    "types-pyyaml>=6.0.12.20260408",
+    "httpx>=0.27",
+    "mkdocs-material>=9.7.6",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+disable_error_code = ["import-untyped"]
+mypy_path = ["src"]
+exclude = [
+    "conftest\\.py$",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+filterwarnings = ["ignore::pytest.PytestCollectionWarning"]

pyoas-0.1.0/src/pyoas/claude/__init__.py

@@ -0,0 +1,3 @@
+from pyoas.claude.scaffolder import SkillScaffolder
+
+__all__ = ["SkillScaffolder"]

pyoas-0.1.0/src/pyoas/claude/scaffolder.py

@@ -0,0 +1,111 @@
+"""
+SkillScaffolder — writes Claude Code skill files for pyoas projects.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from pyoas.core.config import Config
+from pyoas.core.renderer import Renderer
+from pyoas.core.utils import derive_import_path
+
+_DEFAULT_TEMPLATES = Path(__file__).parent / "templates"
+
+
+def _rel(path_str: str) -> str:
+    """Return path_str as a relative path to cwd when possible."""
+    p = Path(path_str)
+    if not p.is_absolute():
+        return path_str
+    try:
+        return str(p.relative_to(Path.cwd()))
+    except ValueError:
+        return path_str
+
+
+class SkillScaffolder:
+    def __init__(self, config: Config) -> None:
+        self._config = config
+
+    def scaffold(self) -> None:
+        if not self._config.skills.generate:
+            return
+        output_dir = Path(self._config.skills.output)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        context = self._build_context()
+        renderer = Renderer(default_templates_dir=_DEFAULT_TEMPLATES)
+        self._scaffold_implement_tests(output_dir, context, renderer)
+        self._scaffold_add_test_case(output_dir, context, renderer)
+        self._scaffold_review_generated(output_dir, context, renderer)
+        self._scaffold_implement_services(output_dir, context, renderer)
+
+    def _scaffold_implement_tests(
+        self, output_dir: Path, context: dict[str, Any], renderer: Renderer
+    ) -> None:
+        skill_file = output_dir / "implement-tests.md"
+        if skill_file.exists() and not self._config.skills.overwrite:
+            typer.echo(f"Skipping {skill_file} (already exists)")
+            return
+        src = renderer.render("implement_tests.md.jinja2", context)
+        skill_file.write_text(src, encoding="utf-8")
+        typer.echo(f"Wrote {skill_file}")
+
+    def _scaffold_add_test_case(
+        self, output_dir: Path, context: dict[str, Any], renderer: Renderer
+    ) -> None:
+        skill_file = output_dir / "add-test-case.md"
+        if skill_file.exists() and not self._config.skills.overwrite:
+            typer.echo(f"Skipping {skill_file} (already exists)")
+            return
+        src = renderer.render("add_test_case.md.jinja2", context)
+        skill_file.write_text(src, encoding="utf-8")
+        typer.echo(f"Wrote {skill_file}")
+
+    def _scaffold_review_generated(
+        self, output_dir: Path, context: dict[str, Any], renderer: Renderer
+    ) -> None:
+        skill_file = output_dir / "review-generated.md"
+        if skill_file.exists() and not self._config.skills.overwrite:
+            typer.echo(f"Skipping {skill_file} (already exists)")
+            return
+        src = renderer.render("review_generated.md.jinja2", context)
+        skill_file.write_text(src, encoding="utf-8")
+        typer.echo(f"Wrote {skill_file}")
+
+    def _scaffold_implement_services(
+        self, output_dir: Path, context: dict[str, Any], renderer: Renderer
+    ) -> None:
+        if not context["has_services"]:
+            return
+        skill_file = output_dir / "implement-services.md"
+        if skill_file.exists() and not self._config.skills.overwrite:
+            typer.echo(f"Skipping {skill_file} (already exists)")
+            return
+        src = renderer.render("implement_services.md.jinja2", context)
+        skill_file.write_text(src, encoding="utf-8")
+        typer.echo(f"Wrote {skill_file}")
+
+    def _build_context(self) -> dict[str, Any]:
+        cfg = self._config
+        tests_output = _rel(cfg.tests.output)
+        services_output = _rel(cfg.services.output) if cfg.services.generate else None
+        models_import = cfg.output.models_import or derive_import_path(
+            cfg.output.models, cfg.output.source_root
+        )
+        return {
+            "spec": _rel(cfg.spec),
+            "tests_output": tests_output,
+            "services_output": services_output,
+            "models_output": _rel(cfg.output.models),
+            "routers_output": _rel(cfg.output.routers),
+            "models_import_path": models_import,
+            "router_import_path": cfg.output.routers_import
+            or derive_import_path(cfg.output.routers, cfg.output.source_root),
+            "has_services": bool(cfg.services.import_path),
+            "not_found_exception": cfg.tests.not_found_exception,
+            "services_pattern": cfg.skills.services_pattern,
+        }