pyopenapi-gen 0.14.3__tar.gz → 0.16.1__tar.gz

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/.github/workflows/semantic-release.yml

@@ -48,6 +48,12 @@ jobs:
       run: |
         poetry install --with dev
 
+    - name: Validate version synchronisation
+      run: |
+        echo "🔍 Checking that all version files are synchronised..."
+        poetry run python scripts/validate_version_sync.py
+        echo "✅ All version files are in sync"
+
     - name: Run comprehensive quality checks
       run: |
         poetry run black --check src/ tests/
@@ -91,6 +97,33 @@ jobs:
         git config user.email "github-actions[bot]@users.noreply.github.com"
         poetry run semantic-release version --skip-build
 
+    - name: Sync version to __init__.py
+      if: steps.check_changes.outputs.release_worthy > 0 || github.event_name == 'workflow_dispatch'
+      env:
+        GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+      run: |
+        echo "🔄 Syncing version from pyproject.toml to __init__.py..."
+
+        # Fetch latest to ensure we have the semantic-release commit
+        git fetch origin main
+        git reset --hard origin/main
+
+        # Run sync script
+        poetry run python scripts/sync_version_to_init.py
+
+        # Check if __init__.py was modified
+        if git diff --quiet src/pyopenapi_gen/__init__.py; then
+          echo "✅ __init__.py already in sync, no changes needed"
+        else
+          echo "📝 __init__.py was updated, creating follow-up commit..."
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/pyopenapi_gen/__init__.py
+          git commit -m "chore(release): sync __init__.py version [skip ci]"
+          git push origin main
+          echo "✅ Version sync complete and committed"
+        fi
+
     - name: Build packages after version bump
       if: steps.check_changes.outputs.release_worthy > 0 || github.event_name == 'workflow_dispatch'
       run: |

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/.gitignore

@@ -195,4 +195,8 @@ _process/
 coverage_reports/
 
 logs
-agent-plan.json
+agent-plan.json
+
+# Bug reports and analysis documents (keep in _process/ folder)
+*-bug-report.md
+*-analysis.md

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/CHANGELOG.md

@@ -1,6 +1,175 @@
 # CHANGELOG
 
 
+## v0.16.1 (2025-10-13)
+
+### Bug Fixes
+
+- **version**: Manually sync __init__.py to 0.16.0 after failed workflow
+  ([`7ee9090`](https://github.com/mindhiveoy/pyopenapi_gen/commit/7ee90902add14d93d471418b56514a8bcafd81cb))
+
+The semantic-release workflow successfully created version 0.16.0 but failed when trying to push the
+  __init__.py sync due to the force-with-lease issue.
+
+This commit manually syncs __init__.py to 0.16.0 to match pyproject.toml. Future releases will use
+  the new workflow logic with follow-up commits.
+
+- **workflow**: Use follow-up commit instead of amending for version sync
+  ([`96f2014`](https://github.com/mindhiveoy/pyopenapi_gen/commit/96f2014bb10ecbfbe3873db32ea6a5f8334542a2))
+
+ISSUE: The git push --force-with-lease was failing with "stale info" because: 1. semantic-release
+  creates and pushes a commit 2. Our sync script tried to amend that commit 3. force-with-lease
+  detected remote had changed and rejected the push
+
+SOLUTION: Changed strategy to use a follow-up commit instead of amending: 1. Fetch latest from
+  origin/main after semantic-release pushes 2. Reset --hard to origin/main to sync local state 3.
+  Run sync script to update __init__.py 4. If changed, create a NEW commit with [skip ci] flag 5.
+  Push normally (no force needed)
+
+Benefits: - Safer: No force-pushing required - Cleaner: Normal git flow with proper commit sequence
+  - Prevents loops: [skip ci] prevents triggering another workflow run
+
+This will result in two commits per release (semantic-release + sync) but is more reliable than
+  force-pushing.
+
+Fixes: https://github.com/mindhiveoy/pyopenapi_gen/actions/runs/18461834318
+
+
+## v0.16.0 (2025-10-13)
+
+### Bug Fixes
+
+- **api**: Improve type annotation for generate_client return type
+  ([`f35d99c`](https://github.com/mindhiveoy/pyopenapi_gen/commit/f35d99c1d2233a20fdd1a69ef0a175ab902513c4))
+
+- Change return type from List[Any] to List[Path] for better type safety - Add proper pathlib.Path
+  import to support the type annotation - Enhances IDE support and type checking for programmatic
+  API users
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-authored-by: Ville Venäläinen <undefined@users.noreply.github.com>
+
+- **api**: Update business_swagger.json descriptions and schemas
+  ([`6496144`](https://github.com/mindhiveoy/pyopenapi_gen/commit/6496144200fb8dfb28275f0d111138107775fa29))
+
+- **lint**: Correct import ordering in __init__.py for Ruff compliance
+  ([`a159807`](https://github.com/mindhiveoy/pyopenapi_gen/commit/a159807fd1932206dd44c805629683998c88707f))
+
+- **release**: Sync __init__.py version automatically in semantic-release workflow
+  ([`7f28674`](https://github.com/mindhiveoy/pyopenapi_gen/commit/7f2867449be1b75b2fc4b7c04073fcad3320e865))
+
+ISSUE: Semantic-release was updating pyproject.toml version but leaving __init__.py at the old
+  version, causing the version validation to fail.
+
+SOLUTION: 1. Fixed immediate issue: Updated __init__.py to match pyproject.toml (0.15.0) 2. Added
+  automatic sync: Created scripts/sync_version_to_init.py to sync version from pyproject.toml to
+  __init__.py 3. Updated workflow: Added step after semantic-release version bump that runs the sync
+  script and amends the commit if __init__.py was updated
+
+This ensures all version files stay synchronized after every semantic-release run.
+
+Fixes: https://github.com/mindhiveoy/pyopenapi_gen/actions/runs/18461374998
+
+- **security**: Address Bandit security warnings with proper logging and nosec annotations
+  ([`f9b0ff3`](https://github.com/mindhiveoy/pyopenapi_gen/commit/f9b0ff3e73ebeaaed49fc631429835ee6e99a33c))
+
+Fixed all Bandit security warnings: - Replace try-except-pass with proper exception logging in
+  parser.py - Replace try-except-pass with logging in telemetry.py - Add nosec B603 annotations to
+  all subprocess.run() calls with explanations - Add nosec B404 annotation to subprocess import with
+  justification
+
+Changes: - parser.py: Log exceptions instead of silent pass for debugging - telemetry.py: Log
+  telemetry failures for debugging - postprocess_manager.py: Document all subprocess calls are safe
+  (hardcoded commands, no shell)
+
+Bandit now reports zero issues (8 properly suppressed with nosec). All quality checks pass.
+
+- **types**: Add binary format mapping to unified type resolver
+  ([`ecba081`](https://github.com/mindhiveoy/pyopenapi_gen/commit/ecba081b37a217277ea61d58b30d1f0a7ac2e04d))
+
+- Add 'binary' to format_mapping in OpenAPISchemaResolver._resolve_string() - Ensures string schemas
+  with format=binary resolve to bytes type - Adds comprehensive test coverage for binary format
+  resolution - Closes gap between legacy and unified type systems
+
+Before: string fields with format=binary were typed as str
+
+After: string fields with format=binary are correctly typed as bytes
+
+### Features
+
+- **api**: Add developer-friendly programmatic API with generate_client()
+  ([`ec8ad0c`](https://github.com/mindhiveoy/pyopenapi_gen/commit/ec8ad0c7b166e9cb523a91d97f8639f050d940c3))
+
+Add a clean, function-based API for programmatic usage alongside the existing CLI.
+
+Key additions: - generate_client() convenience function for simple library usage - Export
+  ClientGenerator and GenerationError at package level - Comprehensive documentation with examples
+  in CLAUDE.md - Full test coverage with 9 new tests in tests/api/
+
+Benefits: - Simple one-function API: generate_client(spec_path, project_root, output_package) - No
+  need to import from deep paths or understand internal structure - Proper error handling with
+  exported GenerationError exception - Fully backward compatible - all existing code continues to
+  work - Matches patterns from similar tools (openapi-python-client, datamodel-code-generator)
+
+Documentation includes: - Basic usage examples - Advanced usage with error handling - Multi-client
+  generation scripts - Build system integration examples - Complete API reference
+
+All tests pass (9 new + existing), type-safe (mypy strict), and quality checks pass.
+
+### Refactoring
+
+- **init**: Remove unused HTTPMethod enum and IR dataclasses
+  ([`7b096ed`](https://github.com/mindhiveoy/pyopenapi_gen/commit/7b096ed321612823976a2e7b7a995d0aaf024312))
+
+
+## v0.15.0 (2025-10-11)
+
+### Bug Fixes
+
+- **release**: Correct semantic-release configuration and sync version to 0.14.3
+  ([`cfa0813`](https://github.com/mindhiveoy/pyopenapi_gen/commit/cfa081393657acfaa0a1c6a29243746748872b28))
+
+Problem: - semantic-release v9 was configured with deprecated `version_pattern` syntax - This caused
+  __init__.py to not be automatically updated during releases - Version validation failed in CI
+  because __init__.py (0.10.2) != pyproject.toml (0.14.3)
+
+Solution: - Updated semantic-release config to use `version_variables` (v9+ syntax) - Synced
+  __init__.py version to 0.14.3 to match pyproject.toml - Now semantic-release will automatically
+  update all version locations
+
+Changes: - pyproject.toml: Changed version_pattern → version_variables -
+  src/pyopenapi_gen/__init__.py: Updated __version__ from 0.10.2 → 0.14.3
+
+This ensures future releases automatically sync all version files.
+
+- **types**: Correct self-import detection to avoid false positives with similar filenames
+  ([`cfee36e`](https://github.com/mindhiveoy/pyopenapi_gen/commit/cfee36e4c8c57d84c0c1d967a7936c5daddf2197))
+
+Problem: - Self-import check used .endswith() for filename comparison - This caused false positives
+  when one filename was a suffix of another - Example:
+  "vector_index_with_embedding_response_data.py".endswith("embedding_response_data.py") == True -
+  Result: Missing imports for forward referenced types, causing NameError at runtime
+
+Solution: - Changed to exact basename comparison using os.path.basename() - Only files with
+  identical basenames are treated as self-imports - Added comprehensive regression tests covering: -
+  Similar module names (not self-imports) - Actual self-references (forward refs without imports) -
+  Exact filename matching requirements
+
+Changes: - src/pyopenapi_gen/types/resolvers/schema_resolver.py: Fixed self-import detection logic -
+  tests/types/test_missing_imports_bug.py: Added 3 regression tests -
+  tests/visit/test_model_visitor.py: Updated test expectations for correct import behavior -
+  .gitignore: Added patterns to ignore bug report and analysis documents
+
+Testing: - All 1309 tests pass - Verified with real business_swagger.json that previously failed -
+  Generated code now includes correct imports for cross-module references
+
+### Features
+
+- **versioning**: Add version synchronization validation script and integrate into quality checks
+  ([`de2ecb8`](https://github.com/mindhiveoy/pyopenapi_gen/commit/de2ecb8c63711230e890bae1cf79f22d5594c551))
+
+
 ## v0.14.3 (2025-10-11)
 
 ### Bug Fixes
@@ -112,6 +281,11 @@ Technical context: - mypy --strict requires explicit types for union type assign
 
 Resolves: mypy error "Incompatible types in assignment (expression has type...)"
 
+### Chores
+
+- Merge latest changes from main
+  ([`44487cc`](https://github.com/mindhiveoy/pyopenapi_gen/commit/44487cce571920b5e2c34814c38cbab67b956097))
+
 ### Code Style
 
 - **format**: Apply Black formatting to modernised type syntax changes
@@ -826,6 +1000,13 @@ All 1,265 tests now pass consistently across environments.
   testing still handled by pr-checks.yml for PRs - This unblocks PR merging while avoiding test
   duplication
 
+- **ci**: Ensure Poetry is available in PATH for semantic-release build command
+  ([`0a68f6e`](https://github.com/mindhiveoy/pyopenapi_gen/commit/0a68f6e4ace7fb998c4ddec14c7cf67713d7ce73))
+
+- Add explicit PATH setup for Poetry before semantic-release step - Add verification step to confirm
+  Poetry availability - Fixes 'poetry: command not found' error in semantic release pipeline -
+  Resolves build command failure preventing automated releases
+
 - **ci**: Ensure Poetry is available in PATH for semantic-release build command
   ([#46](https://github.com/mindhiveoy/pyopenapi_gen/pull/46),
   [`3734aac`](https://github.com/mindhiveoy/pyopenapi_gen/commit/3734aacb74eda746375c7d88c45715a1f18f33a1))

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/CLAUDE.md

@@ -605,6 +605,239 @@ pyopenapi-gen api_v2.yaml --project-root . --output-package pyapis.v2 --core-pac
 # └── v2/                # Second client
 ```
 
+## 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.
+
+### 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}")
+    # Handle error appropriately
+```
+
+#### 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")
+    output_root = Path("src/pyapis")
+
+    # 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.
+
 ## Release Management & Semantic Versioning
 
 ### Automated Release Pipeline

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/Makefile

@@ -66,11 +66,15 @@ security: deps
 	@echo "🔒 Running security checks..."
 	poetry run bandit -r src/ -c pyproject.toml -f json -o coverage_reports/bandit.json || poetry run bandit -r src/ -c pyproject.toml
 
+version-check: deps
+	@echo "🔍 Validating version synchronisation..."
+	poetry run python scripts/validate_version_sync.py
+
 # Combined quality commands
 quality-fix: format lint-fix
 	@echo "✅ Auto-fixed all possible quality issues"
 
-quality: format-check lint typecheck security
+quality: format-check lint typecheck security version-check
 	@echo "✅ All quality checks passed"
 
 # Testing commands
@@ -163,7 +167,7 @@ help:
 	@echo "  clean         - Clean all build artifacts and virtual environment"
 	@echo ""
 	@echo "Quality commands:"
-	@echo "  quality       - Run all quality checks (format, lint, typecheck, security)"
+	@echo "  quality       - Run all quality checks (format, lint, typecheck, security, version)"
 	@echo "  quality-fix   - Auto-fix formatting and linting issues"
 	@echo "  format        - Format code with Black"
 	@echo "  format-check  - Check code formatting"
@@ -171,6 +175,7 @@ help:
 	@echo "  lint-fix      - Auto-fix linting issues"
 	@echo "  typecheck     - Type check with mypy"
 	@echo "  security      - Security scan with Bandit"
+	@echo "  version-check - Validate version synchronisation across files"
 	@echo ""
 	@echo "Testing commands:"
 	@echo "  test          - Run all tests with coverage (parallel, 85% required)"

{pyopenapi_gen-0.14.3 → pyopenapi_gen-0.16.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyopenapi-gen
-Version: 0.14.3
+Version: 0.16.1
 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