pyopenapi-gen 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

pyopenapi_gen/visit/endpoint/generators/signature_generator.py

@@ -10,8 +10,9 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional
 from pyopenapi_gen.core.utils import NameSanitizer
 from pyopenapi_gen.core.writers.code_writer import CodeWriter
 
-# Import necessary helpers from endpoint_utils if they were used directly or indirectly
-from pyopenapi_gen.helpers.endpoint_utils import get_param_type, get_return_type_unified  # Added
+# Import necessary helpers from endpoint_utils
+from pyopenapi_gen.helpers.endpoint_utils import get_param_type
+from pyopenapi_gen.types.strategies.response_strategy import ResponseStrategy
 
 if TYPE_CHECKING:
     from pyopenapi_gen import IROperation
@@ -32,13 +33,15 @@ class EndpointMethodSignatureGenerator:
         op: IROperation,
         context: RenderContext,
         ordered_params: List[Dict[str, Any]],
+        strategy: ResponseStrategy,
     ) -> None:
         """Writes the method signature to the provided CodeWriter."""
         # Logic from EndpointMethodGenerator._write_method_signature
         for p_info in ordered_params:  # Renamed p to p_info to avoid conflict if IRParameter is named p
             context.add_typing_imports_for_type(p_info["type"])
 
-        return_type = get_return_type_unified(op, context, self.schemas)
+        # Use strategy return type instead of computing it again
+        return_type = strategy.return_type
         context.add_typing_imports_for_type(return_type)
 
         # Check if AsyncIterator is in return_type or any parameter type
@@ -63,7 +66,7 @@ class EndpointMethodSignatureGenerator:
         args = ["self"]
         for p_orig in ordered_params:
             p = p_orig.copy()  # Work with a copy
-            arg_str = f"{NameSanitizer.sanitize_method_name(p['name'])}: {p['type']}"  # Ensure param name is sanitized
+            arg_str = f"{NameSanitizer.sanitize_method_name(p["name"])}: {p["type"]}"  # Ensure param name is sanitized
             if not p.get("required", False):
                 # Default value handling: if default is None, it should be ' = None'
                 # If default is a string, it should be ' = "default_value"'

pyopenapi_gen/visit/endpoint/processors/import_analyzer.py

@@ -11,12 +11,12 @@ from typing import TYPE_CHECKING, Any, Dict, Optional  # IO for multipart type h
 from pyopenapi_gen.helpers.endpoint_utils import (
     get_param_type,
     get_request_body_type,
-    get_return_type_unified,
 )
 
 if TYPE_CHECKING:
     from pyopenapi_gen import IROperation  # IRParameter for op.parameters type hint
     from pyopenapi_gen.context.render_context import RenderContext
+    from pyopenapi_gen.types.strategies.response_strategy import ResponseStrategy
 
 logger = logging.getLogger(__name__)
 
@@ -31,6 +31,7 @@ class EndpointImportAnalyzer:
         self,
         op: IROperation,
         context: RenderContext,
+        response_strategy: ResponseStrategy,
     ) -> None:
         """Analyzes the operation and registers imports with the RenderContext."""
         for param in op.parameters:  # op.parameters are IRParameter objects
@@ -60,7 +61,8 @@ class EndpointImportAnalyzer:
             if body_param_type:
                 context.add_typing_imports_for_type(body_param_type)
 
-        return_type = get_return_type_unified(op, context, self.schemas)
+        # Use the response strategy's return type for import analysis
+        return_type = response_strategy.return_type
         context.add_typing_imports_for_type(return_type)
 
         # Check for AsyncIterator in return type or parameter types

pyopenapi_gen/visit/endpoint/processors/parameter_processor.py

@@ -123,7 +123,7 @@ class EndpointParameterProcessor:
                     param_details_map[body_specific_param_info["name"]] = body_specific_param_info
                 else:
                     logger.warning(
-                        f"Request body parameter name '{body_specific_param_info['name']}' "
+                        f"Request body parameter name '{body_specific_param_info["name"]}' "
                         f"for operation '{op.operation_id}'"
                         f"collides with an existing path/query/header parameter. Check OpenAPI spec."
                     )

pyopenapi_gen/visit/model/dataclass_generator.py

@@ -4,7 +4,7 @@ Generates Python code for dataclasses from IRSchema objects.
 
 import json
 import logging
-from typing import Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Tuple
 
 from pyopenapi_gen import IRSchema
 from pyopenapi_gen.context.render_context import RenderContext
@@ -81,6 +81,22 @@ class DataclassGenerator:
                 )
         return "None"
 
+    def _requires_field_mapping(self, api_field: str, python_field: str) -> bool:
+        """Check if field mapping is required between API and Python field names."""
+        return api_field != python_field
+
+    def _generate_field_mappings(self, properties: Dict[str, Any], sanitized_names: Dict[str, str]) -> Dict[str, str]:
+        """Generate field mappings for BaseSchema configuration."""
+        mappings = {}
+        for api_name, python_name in sanitized_names.items():
+            if api_name in properties and self._requires_field_mapping(api_name, python_name):
+                mappings[api_name] = python_name
+        return mappings
+
+    def _has_any_mappings(self, properties: Dict[str, Any], sanitized_names: Dict[str, str]) -> bool:
+        """Check if any field mappings are needed."""
+        return bool(self._generate_field_mappings(properties, sanitized_names))
+
     def generate(
         self,
         schema: IRSchema,
@@ -116,6 +132,7 @@ class DataclassGenerator:
 
         class_name = base_name
         fields_data: List[Tuple[str, str, Optional[str], Optional[str]]] = []
+        field_mappings: Dict[str, str] = {}
 
         if schema.type == "array" and schema.items:
             field_name_for_array_content = "items"
@@ -161,6 +178,10 @@ class DataclassGenerator:
                 # Sanitize the property name for use as a Python attribute
                 field_name = NameSanitizer.sanitize_method_name(prop_name)
 
+                # Track field mapping if the names differ
+                if self._requires_field_mapping(prop_name, field_name):
+                    field_mappings[prop_name] = field_name
+
                 py_type = self.type_service.resolve_schema_type(prop_schema, context, required=is_required)
                 py_type = TypeFinalizer(context)._clean_type(py_type)
 
@@ -168,18 +189,28 @@ class DataclassGenerator:
                 if not is_required:
                     default_expr = self._get_field_default(prop_schema, context)
 
+                # Enhance field documentation for mapped fields
                 field_doc = prop_schema.description
+                if field_mappings.get(prop_name) == field_name and prop_name != field_name:
+                    if field_doc:
+                        field_doc = f"{field_doc} (maps from '{prop_name}')"
+                    else:
+                        field_doc = f"Maps from '{prop_name}'"
+
                 fields_data.append((field_name, py_type, default_expr, field_doc))
 
         # logger.debug(
         #     f"DataclassGenerator: Preparing to render dataclass '{class_name}' with fields: {fields_data}."
         # )
 
+        # Always use BaseSchema for better developer experience
+        # Only include field mappings if there are actual mappings needed
         rendered_code = self.renderer.render_dataclass(
             class_name=class_name,
             fields=fields_data,
             description=schema.description,
             context=context,
+            field_mappings=field_mappings if field_mappings else None,
         )
 
         assert rendered_code.strip(), "Generated dataclass code cannot be empty."

pyopenapi_gen-0.8.5.dist-info/METADATA

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: pyopenapi-gen
+Version: 0.8.5
+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
+Project-URL: Repository, https://github.com/your-org/pyopenapi-gen
+Project-URL: Issues, https://github.com/your-org/pyopenapi-gen/issues
+Project-URL: Changelog, https://github.com/your-org/pyopenapi-gen/blob/main/CHANGELOG.md
+Project-URL: Bug Reports, https://github.com/your-org/pyopenapi-gen/issues
+Project-URL: Source Code, https://github.com/your-org/pyopenapi-gen
+Author-email: Mindhive Oy <contact@mindhive.fi>
+Maintainer-email: Ville Venäläinen | Mindhive Oy <ville@mindhive.fi>
+License: MIT
+License-File: LICENSE
+Keywords: api,async,client,code-generation,enterprise,generator,http,openapi,python,rest,swagger,type-safe
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: <4.0.0,>=3.12
+Requires-Dist: click<8.2.0,>=8.0.0
+Requires-Dist: dataclass-wizard>=0.22.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: openapi-core>=0.19
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer<0.14.0,>=0.12.0
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.7.0; extra == 'dev'
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: dataclass-wizard>=0.22.0; extra == 'dev'
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: mypy>=1.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: safety>=2.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
+Requires-Dist: types-toml>=0.10.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyOpenAPI Generator
+
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+**Modern, enterprise-grade Python client generator for OpenAPI specifications.**
+
+PyOpenAPI Generator creates async-first, strongly-typed Python clients from OpenAPI specs. Built for production use with advanced cycle detection, unified type resolution, and zero runtime dependencies.
+
+## 🚀 Why PyOpenAPI Generator?
+
+### Modern Python Architecture
+- **Async-First**: Built for `async`/`await` with `httpx` for optimal performance
+- **Type Safety**: Complete type hints, dataclass models, and mypy compatibility
+- **Zero Dependencies**: Generated clients are completely self-contained
+
+### Enterprise-Grade Reliability
+- **Advanced Cycle Detection**: Handles complex schemas with circular references
+- **Unified Type Resolution**: Consistent, testable type resolution across all components
+- **Production Ready**: Comprehensive error handling and robust code generation
+
+### Developer Experience
+- **IDE Support**: Rich autocomplete and type checking in modern IDEs
+- **Tag Organization**: Operations grouped by OpenAPI tags for intuitive navigation
+- **Smart Features**: Auto-detected pagination, response unwrapping, and structured exceptions
+
+## 📦 Installation
+
+```bash
+pip install pyopenapi-gen
+```
+
+Or with Poetry:
+```bash
+poetry add pyopenapi-gen
+```
+
+## ⚡ Quick Start
+
+### 1. Generate Your First Client
+```bash
+pyopenapi-gen gen openapi.yaml \
+  --project-root . \
+  --output-package my_api_client
+```
+
+### 2. Use the Generated Client
+```python
+import asyncio
+from my_api_client.client import APIClient
+from my_api_client.core.config import ClientConfig
+
+async def main():
+    config = ClientConfig(base_url="https://api.example.com")
+    async with APIClient(config) as client:
+        # Type-safe API calls with full IDE support
+        users = await client.users.list_users(page=1)
+        
+        # Automatic pagination
+        async for user in client.users.list_users_paginated():
+            print(f"User: {user.name}")
+
+asyncio.run(main())
+```
+
+## 🔧 Configuration Options
+
+### Standalone Client (Default)
+```bash
+pyopenapi-gen gen openapi.yaml \
+  --project-root . \
+  --output-package my_api_client
+```
+Creates self-contained client with embedded core dependencies.
+
+### Shared Core (Multiple Clients)
+```bash
+pyopenapi-gen gen openapi.yaml \
+  --project-root . \
+  --output-package clients.api_client \
+  --core-package clients.core
+```
+Multiple clients share a single core implementation.
+
+### Additional Options
+```bash
+--force           # Overwrite without prompting
+--no-postprocess  # Skip formatting and type checking
+```
+
+## ✨ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔒 **Type Safety** | Complete type hints, dataclass models, and mypy compatibility |
+| ⚡ **Async-First** | Built for modern Python `async`/`await` patterns with `httpx` |
+| 🔌 **Pluggable Auth** | Bearer, API key, OAuth2, and custom authentication strategies |
+| 🔄 **Smart Pagination** | Auto-detected cursor/page/offset patterns with async iteration |
+| 📦 **Zero Dependencies** | Generated clients are completely self-contained |
+| 🛡️ **Robust Parsing** | Advanced cycle detection and graceful handling of complex specs |
+| 🎯 **Structured Errors** | Rich exception hierarchy with meaningful error messages |
+| 🏷️ **Tag Organization** | Operations grouped by OpenAPI tags for intuitive navigation |
+
+## Generated Client Structure
+
+```
+my_api_client/
+├── client.py           # Main APIClient with tag-grouped methods
+├── core/               # Self-contained runtime dependencies
+│   ├── config.py       # Configuration management
+│   ├── http_transport.py # HTTP client abstraction
+│   ├── exceptions.py   # Error hierarchy
+│   └── auth/           # Authentication plugins
+├── models/             # Dataclass models from schemas
+│   └── user.py
+├── endpoints/          # Operation methods grouped by tag
+│   └── users.py
+└── __init__.py
+```
+
+## 🔐 Authentication
+
+PyOpenAPI Generator supports multiple authentication patterns out of the box:
+
+### Bearer Token
+```python
+from my_api_client.core.auth.plugins import BearerAuth
+
+config = ClientConfig(
+    base_url="https://api.example.com",
+    auth=BearerAuth("your-token")
+)
+```
+
+### API Key (Header, Query, or Cookie)
+```python
+from my_api_client.core.auth.plugins import ApiKeyAuth
+
+config = ClientConfig(
+    base_url="https://api.example.com",
+    auth=ApiKeyAuth("your-key", location="header", name="X-API-Key")
+)
+```
+
+### OAuth2 with Refresh
+```python
+from my_api_client.core.auth.plugins import OAuth2Auth
+
+def refresh_token():
+    # Your token refresh logic
+    return "new-token"
+
+config = ClientConfig(
+    base_url="https://api.example.com",
+    auth=OAuth2Auth("initial-token", refresh_callback=refresh_token)
+)
+```
+
+### Composite Authentication
+```python
+from my_api_client.core.auth.base import CompositeAuth
+from my_api_client.core.auth.plugins import BearerAuth, HeadersAuth
+
+config = ClientConfig(
+    base_url="https://api.example.com",
+    auth=CompositeAuth(
+        BearerAuth("token"),
+        HeadersAuth({"X-Custom-Header": "value"})
+    )
+)
+```
+
+## 📊 Advanced Features
+
+### Pagination Support
+```python
+# Manual pagination
+page = 1
+while True:
+    users = await client.users.list_users(page=page, limit=20)
+    if not users:
+        break
+    # Process users
+    page += 1
+
+# Automatic pagination (if supported by the API)
+async for user in client.users.list_users_paginated():
+    print(f"User: {user.name}")
+```
+
+### Error Handling
+```python
+try:
+    user = await client.users.get_user(user_id=123)
+except client.exceptions.UserNotFoundError as e:
+    print(f"User not found: {e.detail}")
+except client.exceptions.ClientError as e:
+    print(f"Client error: {e}")
+except client.exceptions.ServerError as e:
+    print(f"Server error: {e}")
+```
+
+### Response Unwrapping
+Many APIs wrap responses in a `data` field. PyOpenAPI Generator automatically detects and unwraps these patterns:
+
+```python
+# API returns: {"data": {"id": 1, "name": "John"}, "meta": {...}}
+# Your code receives: User(id=1, name="John")
+user = await client.users.get_user(user_id=1)
+print(user.name)  # "John"
+```
+
+## 🚧 Known Limitations
+
+Some OpenAPI features have simplified implementations. Contributions welcome!
+
+| Limitation | Current Behavior |
+|------------|------------------|
+| **Parameter Serialization** | Uses HTTP client defaults instead of OpenAPI `style`/`explode` |
+| **Complex Multipart** | Basic file upload support; complex schemas simplified |
+| **Response Headers** | Only response body returned, headers ignored |
+| **Parameter Defaults** | Schema defaults not applied to method signatures |
+
+> 💡 **Contributing**: See our [Contributing Guide](CONTRIBUTING.md) to help enhance OpenAPI specification coverage!
+
+## 🏗️ Architecture
+
+PyOpenAPI Generator uses a sophisticated three-stage pipeline designed for enterprise-grade reliability:
+
+```mermaid
+graph TD
+    A[OpenAPI Spec] --> B[Loading Stage]
+    B --> C[Intermediate Representation]
+    C --> D[Unified Type Resolution]
+    D --> E[Visiting Stage]
+    E --> F[Python Code AST]
+    F --> G[Emitting Stage]
+    G --> H[Generated Files]
+    H --> I[Post-Processing]
+    I --> J[Final Client Package]
+    
+    subgraph "Key Components"
+        K[Schema Parser]
+        L[Cycle Detection]
+        M[Reference Resolution]
+        N[Type Service]
+        O[Code Emitters]
+    end
+```
+
+### Why This Architecture?
+
+**Complex Schema Handling**: Modern OpenAPI specs contain circular references, deep nesting, and intricate type relationships. Our architecture handles these robustly.
+
+**Production Ready**: Each stage has clear responsibilities and clean interfaces, enabling comprehensive testing and reliable code generation.
+
+**Extensible**: Plugin-based authentication, customizable type resolution, and modular emitters make the system adaptable to various use cases.
+
+## 📚 Documentation
+
+- **[Architecture Guide](docs/architecture.md)** - Deep dive into the system design
+- **[Type Resolution](docs/unified_type_resolution.md)** - How types are resolved and generated
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
+- **[API Reference](docs/)** - Complete API documentation
+
+## 🤝 Contributing
+
+We welcome contributions! PyOpenAPI Generator is designed to be extensible and maintainable.
+
+### Quick Start for Contributors
+```bash
+# 1. Fork and clone the repository
+git clone https://github.com/your-username/pyopenapi-gen.git
+cd pyopenapi-gen
+
+# 2. Set up development environment
+source .venv/bin/activate  # Activate virtual environment
+poetry install --with dev
+
+# 3. Run quality checks
+make quality-fix  # Auto-fix formatting and linting
+make quality      # Run all quality checks
+make test         # Run tests with coverage
+```
+
+### Development Workflow
+```bash
+# Essential commands for development
+make quality-fix    # Auto-fix formatting and linting issues
+make quality        # Run all quality checks (format, lint, typecheck, security)
+make test          # Run tests with 85% coverage requirement
+make test-fast     # Run tests, stop on first failure
+
+# Individual quality commands
+make format        # Format code with Black
+make lint-fix      # Fix linting issues with Ruff
+make typecheck     # Type checking with mypy
+make security      # Security scanning with Bandit
+```
+
+See our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
+- 📋 Development setup and workflow
+- 🧪 Testing guidelines and standards
+- 📖 Documentation standards
+- 🔄 Pull request process
+- 🏗️ Architecture and design patterns
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+Generated clients are self-contained and can be distributed under any license compatible with your project.
+
+## 🙏 Acknowledgments
+
+- Built with [httpx](https://www.python-httpx.org/) for modern async HTTP
+- Type safety with [mypy](https://mypy.readthedocs.io/) strict mode
+- Code quality with [Black](https://black.readthedocs.io/) and [Ruff](https://docs.astral.sh/ruff/)
+- Visitor pattern for clean, maintainable code generation
+
+---
+
+**Made with ❤️ for the Python community**