From 2f444a93ad65ab6e28a0cba5594f1ffb6b043662 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 10 Jan 2026 17:43:52 +0530 Subject: [PATCH] doc changes from fastapi openapi first to openapi first. added cli docs --- docs/openapi_first/cli.md | 3 ++ mkdocs.yml | 5 ++- openapi_first/__init__.py | 14 ++++----- openapi_first/app.py | 4 +-- openapi_first/binder.py | 2 +- openapi_first/cli.py | 66 ++++++++++++++++++++++++++++++++++++--- openapi_first/errors.py | 2 +- openapi_first/loader.py | 2 +- 8 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 docs/openapi_first/cli.md diff --git a/docs/openapi_first/cli.md b/docs/openapi_first/cli.md new file mode 100644 index 0000000..eaaadc2 --- /dev/null +++ b/docs/openapi_first/cli.md @@ -0,0 +1,3 @@ +# Cli + +::: openapi_first.cli diff --git a/mkdocs.yml b/mkdocs.yml index 53bd282..f201bd5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,10 @@ nav: - Core: - OpenAPI-First App: openapi_first/app.md - Route Binder: openapi_first/binder.md - - Spec Loaders: openapi_first/loaders.md + - Spec Loaders: openapi_first/loader.md + + - CLI: + - Home: openapi_first/cli.md - Errors: - Error Hierarchy: openapi_first/errors.md diff --git a/openapi_first/__init__.py b/openapi_first/__init__.py index 814d64c..f7e9ea9 100644 --- a/openapi_first/__init__.py +++ b/openapi_first/__init__.py @@ -33,11 +33,11 @@ Installation Install using pip: - pip install fastapi-openapi-first + pip install openapi-first Or with Poetry: - poetry add fastapi-openapi-first + poetry add openapi-first Runtime dependencies are intentionally minimal: - fastapi @@ -53,7 +53,7 @@ Basic Usage Minimal OpenAPI-first FastAPI application: - from fastapi_openapi_first import app + from openapi_first import app import my_service.routes as routes api = app.OpenAPIFirstApp( @@ -104,10 +104,10 @@ Public API Surface The supported public API consists of the following top-level modules: -- fastapi_openapi_first.app -- fastapi_openapi_first.binder -- fastapi_openapi_first.loader -- fastapi_openapi_first.errors +- openapi_first.app +- openapi_first.binder +- openapi_first.loader +- openapi_first.errors Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root. diff --git a/openapi_first/app.py b/openapi_first/app.py index b0744bd..f816e09 100644 --- a/openapi_first/app.py +++ b/openapi_first/app.py @@ -1,5 +1,5 @@ """ -fastapi_openapi_first.app +openapi_first.app ========================= OpenAPI-first application bootstrap for FastAPI. @@ -84,7 +84,7 @@ class OpenAPIFirstApp(FastAPI): Example ------- - >>> from fastapi_openapi_first import OpenAPIFirstApp + >>> from openapi_first import OpenAPIFirstApp >>> import app.routes as routes >>> >>> app = OpenAPIFirstApp( diff --git a/openapi_first/binder.py b/openapi_first/binder.py index fb5fda1..e10d31c 100644 --- a/openapi_first/binder.py +++ b/openapi_first/binder.py @@ -1,5 +1,5 @@ """ -fastapi_openapi_first.binder +openapi_first.binder ============================ OpenAPI-driven route binding for FastAPI. diff --git a/openapi_first/cli.py b/openapi_first/cli.py index cb1b1fb..e148183 100644 --- a/openapi_first/cli.py +++ b/openapi_first/cli.py @@ -1,21 +1,79 @@ -import shutil +""" +openapi_first.cli +======================== + +Command-line interface for FastAPI OpenAPI-first scaffolding utilities. + +This module provides a small, focused CLI intended to help developers +quickly bootstrap OpenAPI-first FastAPI services using bundled project +templates. + +Currently supported scaffolds: +- Health check service (minimal OpenAPI-first application) + +The CLI copies versioned templates packaged with the library into a +user-specified directory, allowing rapid local development without +manual setup. +""" + import argparse +import shutil from pathlib import Path from importlib import resources def copy_health_app_template(target_dir: Path) -> None: """ - Copy the bundled health app template into a target directory. + Copy the bundled OpenAPI-first health app template into a directory. + + This function copies a fully working, minimal OpenAPI-first FastAPI + health check application from the package's embedded templates into + the specified target directory. + + The target directory will be created if it does not already exist. + Existing files may be overwritten. + + Parameters + ---------- + target_dir : pathlib.Path + Destination directory into which the health app template + should be copied. + + Raises + ------ + FileNotFoundError + If the bundled health app template cannot be located. """ target_dir = target_dir.resolve() target_dir.mkdir(parents=True, exist_ok=True) - with resources.files("fastapi_openapi_first.templates").joinpath("health_app") as src: + with resources.files("openapi_first.templates").joinpath( + "health_app" + ) as src: shutil.copytree(src, target_dir, dirs_exist_ok=True) -def main(): +def main() -> None: + """ + Entry point for the FastAPI OpenAPI-first CLI. + + Parses command-line arguments and initializes a new OpenAPI-first + health check application by copying the bundled template into the + specified directory. + + If no target path is provided, the scaffold is created in a directory + named ``health-app`` in the current working directory. + + Example + ------- + Create a health app in the default directory:: + + openapi-first + + Create a health app in a custom directory:: + + openapi-first my-service + """ parser = argparse.ArgumentParser( description="FastAPI OpenAPI-first scaffolding tools" ) diff --git a/openapi_first/errors.py b/openapi_first/errors.py index 4742183..f2b712d 100644 --- a/openapi_first/errors.py +++ b/openapi_first/errors.py @@ -1,5 +1,5 @@ """ -fastapi_openapi_first.errors +openapi_first.errors ============================ Custom exceptions for OpenAPI-first FastAPI applications. diff --git a/openapi_first/loader.py b/openapi_first/loader.py index e0e2b51..4869e68 100644 --- a/openapi_first/loader.py +++ b/openapi_first/loader.py @@ -1,5 +1,5 @@ """ -fastapi_openapi_first.loaders +openapi_first.loaders ============================= OpenAPI specification loading and validation utilities.