pyopenapi-gen 0.17.0__tar.gz → 0.19.0__tar.gz

{pyopenapi_gen-0.17.0 → pyopenapi_gen-0.19.0}/CHANGELOG.md

@@ -1,6 +1,106 @@
 # CHANGELOG
 
 
+## v0.19.0 (2025-10-18)
+
+### Chores
+
+- **release**: Sync __init__.py version [skip ci]
+  ([`4938f48`](https://github.com/mindhiveoy/pyopenapi_gen/commit/4938f4840650dc56573ca3294d782f74ea89dc65))
+
+### Features
+
+- **codegen**: Integrate DataclassSerializer for request body serialization
+  ([`0b5b01f`](https://github.com/mindhiveoy/pyopenapi_gen/commit/0b5b01f3e7a5a1d7d57298088bf2543920517855))
+
+
+## v0.18.0 (2025-10-14)
+
+### Bug Fixes
+
+- **ci**: Add github_token to Claude Code action
+  ([`e3a18d5`](https://github.com/mindhiveoy/pyopenapi_gen/commit/e3a18d5377c206c9735981c588999decdf361fdf))
+
+Fixes workflow validation error when Claude workflow differs between branches. The action requires
+  either: 1. Identical workflow file on main branch, OR 2. Explicit github_token parameter
+
+Adding github_token allows the action to work on PR branches with workflow modifications before
+  they're merged to main.
+
+- **ci**: Allow dependabot in semantic-release and optimize Claude Code reviews
+  ([`717e90c`](https://github.com/mindhiveoy/pyopenapi_gen/commit/717e90c3a8bff13757434fb1375b0b7a30968fd9))
+
+1. Added dependabot and renovate to semantic-release allowed_bots list - Fixes: Workflow initiated
+  by non-human actor error - Allows automated dependency updates to trigger releases
+
+2. Updated Claude Code workflow prompt to skip quality gates - CI pipeline already runs: Black,
+  Ruff, mypy, Bandit, pytest - Claude now focuses on: code logic, security, architecture - Avoids
+  duplicate work and speeds up reviews
+
+These changes reduce CI time and eliminate redundant quality checks.
+
+### Chores
+
+- **deps**: Update idna to version 3.11 and adjust python version requirement
+  ([`a4adacb`](https://github.com/mindhiveoy/pyopenapi_gen/commit/a4adacbda45ec8e9b67b8734b7867188b38c2fc1))
+
+- **release**: Sync __init__.py version [skip ci]
+  ([`1f0e3af`](https://github.com/mindhiveoy/pyopenapi_gen/commit/1f0e3af6937d63394c6c0250e19890278f1a7bd1))
+
+### Documentation
+
+- **readme**: Add comprehensive programmatic API documentation
+  ([`d2fca57`](https://github.com/mindhiveoy/pyopenapi_gen/commit/d2fca57f62b0a1c5f718401df3c1b8ac7a7bb02b))
+
+Added detailed documentation for using pyopenapi_gen as a Python library:
+
+- Why programmatic usage section - Architecture diagram with mermaid - Basic usage examples -
+  Advanced usage with all options - Multi-client generation script - Build system integration
+  example - Complete API reference - Comparison: CLI vs programmatic usage
+
+This documentation covers the generate_client() function, ClientGenerator class, and GenerationError
+  exception, making it easy for users to integrate the generator into their build systems, CI/CD
+  pipelines, and custom tooling.
+
+### Features
+
+- **codegen**: Add @overload support for multi-content-type operations
+  ([`bf608a7`](https://github.com/mindhiveoy/pyopenapi_gen/commit/bf608a7c47dc4c528f407456478002e3d6779886))
+
+Implement PEP 484 @overload signatures for operations accepting multiple content types
+  (application/json, multipart/form-data, etc.). Enables IDE autocomplete and type checking for
+  endpoints with varying request formats.
+
+Technical approach: - OverloadMethodGenerator creates @overload decorators per content type -
+  Literal types constrain content_type parameter per overload - Type-safe parameter mapping:
+  JSON→body, multipart→files, form→data - Assert statements for mypy type narrowing (validated,
+  marked nosec B101)
+
+This addresses developer experience issues when working with upload endpoints that accept both JSON
+  metadata and multipart file uploads.
+
+- **codegen**: Integrate @overload generation into endpoint method generator
+  ([`d29cd13`](https://github.com/mindhiveoy/pyopenapi_gen/commit/d29cd131ed498c389366712eb873430ec0eb7e37))
+
+Refactor EndpointMethodGenerator to detect multi-content-type operations and delegate to
+  OverloadMethodGenerator for type-safe signature generation. Maintains full backward compatibility
+  for single-content-type operations.
+
+Implementation: - generate() branches on has_multiple_content_types() check -
+  _generate_standard_method() preserves existing single-content-type logic -
+  _generate_overloaded_method() orchestrates overload generation + runtime dispatch - Runtime
+  dispatch validates exactly one content-type parameter provided
+
+Developers now receive accurate IDE autocomplete for multi-format endpoints, eliminating guesswork
+  about which parameters are valid for each content type.
+
+- **spec**: Update business_swagger.json with multi-content-type example
+  ([`5007e77`](https://github.com/mindhiveoy/pyopenapi_gen/commit/5007e7752440856f7111a7422af09ca6da8a5a5a))
+
+- Update listDocuments endpoint with cursor and page-based pagination - Provides real-world example
+  for content-type overloading implementation
+
+
 ## v0.17.0 (2025-10-13)
 
 ### Chores

{pyopenapi_gen-0.17.0 → pyopenapi_gen-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenapi-gen
-Version: 0.17.0
+Version: 0.19.0
 Summary: Modern, async-first Python client generator for OpenAPI specifications with advanced cycle detection and unified type resolution
 Project-URL: Homepage, https://github.com/your-org/pyopenapi-gen
 Project-URL: Documentation, https://github.com/your-org/pyopenapi-gen/blob/main/README.md
@@ -123,6 +123,254 @@ async def main():
 asyncio.run(main())
 ```
 
+## 🐍 Using as a Library (Programmatic API)
+
+### Why Programmatic Usage?
+The generator was designed to work both as a CLI tool and as a Python library. Programmatic usage enables integration with build systems, CI/CD pipelines, code generators, and custom tooling. You get the same powerful code generation capabilities with full Python API access.
+
+### What Is the Programmatic API?
+A simple, function-based API that wraps the internal `ClientGenerator` class, providing a clean entry point for library usage without requiring knowledge of internal structure.
+
+```mermaid
+graph TD
+    A[Your Build Script] --> B[generate_client Function]
+    B --> C[ClientGenerator]
+    C --> D[Load OpenAPI Spec]
+    D --> E[Generate Code]
+    E --> F[Write Files]
+    F --> G[Post-Process]
+    G --> H[Return File List]
+    
+    subgraph "Public API"
+        B
+        I[ClientGenerator Class]
+        J[GenerationError Exception]
+    end
+    
+    subgraph "Advanced API"
+        K[load_ir_from_spec]
+        L[IR Models]
+        M[WarningCollector]
+    end
+```
+
+### How to Use Programmatically
+
+#### Basic Usage
+```python
+from pyopenapi_gen import generate_client
+
+# Simple client generation
+files = generate_client(
+    spec_path="input/openapi.yaml",
+    project_root=".",
+    output_package="pyapis.my_client"
+)
+
+print(f"Generated {len(files)} files")
+```
+
+#### Advanced Usage with All Options
+```python
+from pyopenapi_gen import generate_client, GenerationError
+
+try:
+    files = generate_client(
+        spec_path="input/openapi.yaml",
+        project_root=".",
+        output_package="pyapis.my_client",
+        core_package="pyapis.core",  # Optional shared core
+        force=True,                   # Overwrite without diff check
+        no_postprocess=False,         # Run Black + mypy
+        verbose=True                  # Show progress
+    )
+
+    # Process generated files
+    for file_path in files:
+        print(f"Generated: {file_path}")
+
+except GenerationError as e:
+    print(f"Generation failed: {e}")
+```
+
+#### Multi-Client Generation Script
+```python
+from pyopenapi_gen import generate_client
+from pathlib import Path
+
+# Configuration for multiple clients
+clients = [
+    {"spec": "api_v1.yaml", "package": "pyapis.client_v1"},
+    {"spec": "api_v2.yaml", "package": "pyapis.client_v2"},
+]
+
+# Shared core package
+core_package = "pyapis.core"
+
+# Generate all clients
+for client_config in clients:
+    print(f"Generating {client_config['package']}...")
+    
+    generate_client(
+        spec_path=client_config["spec"],
+        project_root=".",
+        output_package=client_config["package"],
+        core_package=core_package,
+        force=True,
+        verbose=True
+    )
+
+print("All clients generated successfully!")
+```
+
+#### Integration with Build Systems
+```python
+# Example: Custom build script
+import sys
+from pathlib import Path
+from pyopenapi_gen import generate_client, GenerationError
+
+def build_api_clients():
+    """Generate all API clients as part of build process"""
+    
+    specs_dir = Path("specs")
+    
+    # Find all OpenAPI specs
+    spec_files = list(specs_dir.glob("*.yaml")) + list(specs_dir.glob("*.json"))
+    
+    if not spec_files:
+        print("No OpenAPI specs found in specs/")
+        return False
+    
+    # Generate clients
+    for spec_file in spec_files:
+        client_name = spec_file.stem
+        package_name = f"pyapis.{client_name}"
+        
+        print(f"Generating client for {spec_file.name}...")
+        
+        try:
+            generate_client(
+                spec_path=str(spec_file),
+                project_root="src",
+                output_package=package_name,
+                core_package="pyapis.core",
+                force=True
+            )
+        except GenerationError as e:
+            print(f"Failed to generate {client_name}: {e}", file=sys.stderr)
+            return False
+    
+    return True
+
+if __name__ == "__main__":
+    success = build_api_clients()
+    sys.exit(0 if success else 1)
+```
+
+### API Reference
+
+#### `generate_client()` Function
+
+```python
+def generate_client(
+    spec_path: str,
+    project_root: str,
+    output_package: str,
+    core_package: str | None = None,
+    force: bool = False,
+    no_postprocess: bool = False,
+    verbose: bool = False,
+) -> List[Path]
+```
+
+**Parameters**:
+- `spec_path`: Path to OpenAPI spec file (YAML or JSON)
+- `project_root`: Root directory of your Python project
+- `output_package`: Python package name (e.g., `'pyapis.my_client'`)
+- `core_package`: Optional shared core package name (defaults to `{output_package}.core`)
+- `force`: Skip diff check and overwrite existing output
+- `no_postprocess`: Skip Black formatting and mypy type checking
+- `verbose`: Print detailed progress information
+
+**Returns**: List of `Path` objects for all generated files
+
+**Raises**: `GenerationError` if generation fails
+
+#### `ClientGenerator` Class (Advanced)
+
+For advanced use cases requiring more control:
+
+```python
+from pyopenapi_gen import ClientGenerator, GenerationError
+from pathlib import Path
+
+# Create generator with custom settings
+generator = ClientGenerator(verbose=True)
+
+# Generate with full control
+try:
+    files = generator.generate(
+        spec_path="openapi.yaml",
+        project_root=Path("."),
+        output_package="pyapis.my_client",
+        core_package="pyapis.core",
+        force=False,
+        no_postprocess=False
+    )
+except GenerationError as e:
+    print(f"Generation failed: {e}")
+```
+
+#### `GenerationError` Exception
+
+Raised when generation fails. Contains contextual information about the failure:
+
+```python
+from pyopenapi_gen import generate_client, GenerationError
+
+try:
+    generate_client(
+        spec_path="invalid.yaml",
+        project_root=".",
+        output_package="test"
+    )
+except GenerationError as e:
+    # Exception message includes context
+    print(f"Error: {e}")
+    # Typical causes:
+    # - Invalid OpenAPI specification
+    # - File I/O errors
+    # - Type checking failures
+    # - Invalid project structure
+```
+
+### Comparison: CLI vs Programmatic API
+
+**CLI Usage**:
+```bash
+pyopenapi-gen input/openapi.yaml \
+  --project-root . \
+  --output-package pyapis.my_client \
+  --force \
+  --verbose
+```
+
+**Equivalent Programmatic Usage**:
+```python
+from pyopenapi_gen import generate_client
+
+generate_client(
+    spec_path="input/openapi.yaml",
+    project_root=".",
+    output_package="pyapis.my_client",
+    force=True,
+    verbose=True
+)
+```
+
+Both approaches use the same underlying implementation and produce identical results.
+
 ## 🔧 Configuration Options
 
 ### Standalone Client (Default)

{pyopenapi_gen-0.17.0 → pyopenapi_gen-0.19.0}/README.md

@@ -65,6 +65,254 @@ async def main():
 asyncio.run(main())
 ```
 
+## 🐍 Using as a Library (Programmatic API)
+
+### Why Programmatic Usage?
+The generator was designed to work both as a CLI tool and as a Python library. Programmatic usage enables integration with build systems, CI/CD pipelines, code generators, and custom tooling. You get the same powerful code generation capabilities with full Python API access.
+
+### What Is the Programmatic API?
+A simple, function-based API that wraps the internal `ClientGenerator` class, providing a clean entry point for library usage without requiring knowledge of internal structure.
+
+```mermaid
+graph TD
+    A[Your Build Script] --> B[generate_client Function]
+    B --> C[ClientGenerator]
+    C --> D[Load OpenAPI Spec]
+    D --> E[Generate Code]
+    E --> F[Write Files]
+    F --> G[Post-Process]
+    G --> H[Return File List]
+    
+    subgraph "Public API"
+        B
+        I[ClientGenerator Class]
+        J[GenerationError Exception]
+    end
+    
+    subgraph "Advanced API"
+        K[load_ir_from_spec]
+        L[IR Models]
+        M[WarningCollector]
+    end
+```
+
+### How to Use Programmatically
+
+#### Basic Usage
+```python
+from pyopenapi_gen import generate_client
+
+# Simple client generation
+files = generate_client(
+    spec_path="input/openapi.yaml",
+    project_root=".",
+    output_package="pyapis.my_client"
+)
+
+print(f"Generated {len(files)} files")
+```
+
+#### Advanced Usage with All Options
+```python
+from pyopenapi_gen import generate_client, GenerationError
+
+try:
+    files = generate_client(
+        spec_path="input/openapi.yaml",
+        project_root=".",
+        output_package="pyapis.my_client",
+        core_package="pyapis.core",  # Optional shared core
+        force=True,                   # Overwrite without diff check
+        no_postprocess=False,         # Run Black + mypy
+        verbose=True                  # Show progress
+    )
+
+    # Process generated files
+    for file_path in files:
+        print(f"Generated: {file_path}")
+
+except GenerationError as e:
+    print(f"Generation failed: {e}")
+```
+
+#### Multi-Client Generation Script
+```python
+from pyopenapi_gen import generate_client
+from pathlib import Path
+
+# Configuration for multiple clients
+clients = [
+    {"spec": "api_v1.yaml", "package": "pyapis.client_v1"},
+    {"spec": "api_v2.yaml", "package": "pyapis.client_v2"},
+]
+
+# Shared core package
+core_package = "pyapis.core"
+
+# Generate all clients
+for client_config in clients:
+    print(f"Generating {client_config['package']}...")
+    
+    generate_client(
+        spec_path=client_config["spec"],
+        project_root=".",
+        output_package=client_config["package"],
+        core_package=core_package,
+        force=True,
+        verbose=True
+    )
+
+print("All clients generated successfully!")
+```
+
+#### Integration with Build Systems
+```python
+# Example: Custom build script
+import sys
+from pathlib import Path
+from pyopenapi_gen import generate_client, GenerationError
+
+def build_api_clients():
+    """Generate all API clients as part of build process"""
+    
+    specs_dir = Path("specs")
+    
+    # Find all OpenAPI specs
+    spec_files = list(specs_dir.glob("*.yaml")) + list(specs_dir.glob("*.json"))
+    
+    if not spec_files:
+        print("No OpenAPI specs found in specs/")
+        return False
+    
+    # Generate clients
+    for spec_file in spec_files:
+        client_name = spec_file.stem
+        package_name = f"pyapis.{client_name}"
+        
+        print(f"Generating client for {spec_file.name}...")
+        
+        try:
+            generate_client(
+                spec_path=str(spec_file),
+                project_root="src",
+                output_package=package_name,
+                core_package="pyapis.core",
+                force=True
+            )
+        except GenerationError as e:
+            print(f"Failed to generate {client_name}: {e}", file=sys.stderr)
+            return False
+    
+    return True
+
+if __name__ == "__main__":
+    success = build_api_clients()
+    sys.exit(0 if success else 1)
+```
+
+### API Reference
+
+#### `generate_client()` Function
+
+```python
+def generate_client(
+    spec_path: str,
+    project_root: str,
+    output_package: str,
+    core_package: str | None = None,
+    force: bool = False,
+    no_postprocess: bool = False,
+    verbose: bool = False,
+) -> List[Path]
+```
+
+**Parameters**:
+- `spec_path`: Path to OpenAPI spec file (YAML or JSON)
+- `project_root`: Root directory of your Python project
+- `output_package`: Python package name (e.g., `'pyapis.my_client'`)
+- `core_package`: Optional shared core package name (defaults to `{output_package}.core`)
+- `force`: Skip diff check and overwrite existing output
+- `no_postprocess`: Skip Black formatting and mypy type checking
+- `verbose`: Print detailed progress information
+
+**Returns**: List of `Path` objects for all generated files
+
+**Raises**: `GenerationError` if generation fails
+
+#### `ClientGenerator` Class (Advanced)
+
+For advanced use cases requiring more control:
+
+```python
+from pyopenapi_gen import ClientGenerator, GenerationError
+from pathlib import Path
+
+# Create generator with custom settings
+generator = ClientGenerator(verbose=True)
+
+# Generate with full control
+try:
+    files = generator.generate(
+        spec_path="openapi.yaml",
+        project_root=Path("."),
+        output_package="pyapis.my_client",
+        core_package="pyapis.core",
+        force=False,
+        no_postprocess=False
+    )
+except GenerationError as e:
+    print(f"Generation failed: {e}")
+```
+
+#### `GenerationError` Exception
+
+Raised when generation fails. Contains contextual information about the failure:
+
+```python
+from pyopenapi_gen import generate_client, GenerationError
+
+try:
+    generate_client(
+        spec_path="invalid.yaml",
+        project_root=".",
+        output_package="test"
+    )
+except GenerationError as e:
+    # Exception message includes context
+    print(f"Error: {e}")
+    # Typical causes:
+    # - Invalid OpenAPI specification
+    # - File I/O errors
+    # - Type checking failures
+    # - Invalid project structure
+```
+
+### Comparison: CLI vs Programmatic API
+
+**CLI Usage**:
+```bash
+pyopenapi-gen input/openapi.yaml \
+  --project-root . \
+  --output-package pyapis.my_client \
+  --force \
+  --verbose
+```
+
+**Equivalent Programmatic Usage**:
+```python
+from pyopenapi_gen import generate_client
+
+generate_client(
+    spec_path="input/openapi.yaml",
+    project_root=".",
+    output_package="pyapis.my_client",
+    force=True,
+    verbose=True
+)
+```
+
+Both approaches use the same underlying implementation and produce identical results.
+
 ## 🔧 Configuration Options
 
 ### Standalone Client (Default)