otterapi 0.0.5__py3-none-any.whl → 0.0.6__py3-none-any.whl

otterapi/cli.py

@@ -1,13 +1,32 @@
+"""Command-line interface for OtterAPI.
+
+This module provides the CLI commands for generating Python client code
+from OpenAPI specifications.
+"""
+
+import json
+import logging
+import traceback
+from pathlib import Path
 from typing import Annotated
 
 import typer
+import yaml
 from rich.console import Console
+from rich.logging import RichHandler
+from rich.panel import Panel
 from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.syntax import Syntax
+from rich.table import Table
 
-from otterapi.codegen.generator import Codegen
-from otterapi.config import get_config
+from otterapi.codegen.codegen import Codegen
+from otterapi.codegen.schema import SchemaLoader
+from otterapi.config import CodegenConfig, DocumentConfig, get_config
+from otterapi.exceptions import OtterAPIError, SchemaLoadError, SchemaValidationError
 
 console = Console()
+error_console = Console(stderr=True)
+
 app = typer.Typer(
     name='otterapi',
     help='Generate Python client code from OpenAPI specifications',
@@ -15,6 +34,23 @@ app = typer.Typer(
 )
 
 
+def setup_logging(verbose: bool = False, debug: bool = False) -> None:
+    """Configure logging based on verbosity settings."""
+    if debug:
+        level = logging.DEBUG
+    elif verbose:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+
+    logging.basicConfig(
+        level=level,
+        format='%(message)s',
+        datefmt='[%X]',
+        handlers=[RichHandler(console=error_console, rich_tracebacks=True)],
+    )
+
+
 @app.command()
 def generate(
     config: Annotated[
@@ -23,62 +59,324 @@ def generate(
             '--config', '-c', help='Path to configuration file (YAML or JSON)'
         ),
     ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option(
+            '--source', '-s', help='Direct path or URL to OpenAPI specification'
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        typer.Option('--output', '-o', help='Output directory for generated code'),
+    ] = None,
+    verbose: Annotated[
+        bool, typer.Option('--verbose', '-v', help='Enable verbose output')
+    ] = False,
+    debug: Annotated[bool, typer.Option('--debug', help='Enable debug output')] = False,
 ) -> None:
-    """Generate Python client code from configuration.
+    """Generate Python client code from OpenAPI specifications.
 
-    If no config file is specified, will look for default config files
-    in the current directory or use environment variables.
+    You can either use a configuration file or specify the source and output
+    directly via command-line options.
 
     Examples:
         otterapi generate
         otterapi generate --config my-config.yaml
         otterapi generate -c config.json
+        otterapi generate --source https://api.example.com/openapi.json --output ./client
+        otterapi generate -s ./api.yaml -o ./generated
     """
-    config = get_config(config)
+    setup_logging(verbose, debug)
 
     try:
-        with Progress(
-            SpinnerColumn(),
-            TextColumn('[progress.description]{task.description}'),
-            console=console,
-        ) as progress:
-            for document_config in config.documents:
+        # Build configuration from options or file
+        if source and output:
+            codegen_config = CodegenConfig(
+                documents=[DocumentConfig(source=source, output=output)]
+            )
+        elif source or output:
+            error_console.print(
+                '[red]Error:[/red] Both --source and --output must be provided together'
+            )
+            raise typer.Exit(1)
+        else:
+            try:
+                codegen_config = get_config(config)
+            except FileNotFoundError as e:
+                error_console.print(f'[red]Error:[/red] {e}')
+                error_console.print(
+                    '\n[dim]Hint: Run [bold]otterapi init[/bold] to create a configuration file,[/dim]'
+                )
+                error_console.print(
+                    '[dim]or use [bold]--source[/bold] and [bold]--output[/bold] options.[/dim]'
+                )
+                raise typer.Exit(1)
+
+        for document_config in codegen_config.documents:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn('[progress.description]{task.description}'),
+                console=console,
+            ) as progress:
                 task = progress.add_task(
-                    f'Generating code for {document_config.source} in {document_config.output}...',
+                    f'Generating code for {document_config.source}...',
                     total=None,
                 )
 
                 codegen = Codegen(document_config)
-                codegen.generate()
 
-                console.print(
-                    f"[green]✓[/green] Successfully generated code in '{document_config.output}'"
+                generated_files = codegen.generate()
+                progress.update(
+                    task,
+                    description=f'Code generation completed for {document_config.source}!',
                 )
+
                 console.print('[dim]Generated files:[/dim]')
-                console.print(
-                    f'  - {document_config.output}/{document_config.models_file}'
-                )
-                console.print(
-                    f'  - {document_config.output}/{document_config.endpoints_file}'
-                )
+                for file_path in generated_files:
+                    console.print(f'  - {file_path}')
 
-            progress.update(task, description='Code generation completed!')
+        console.print('\n[green]✓[/green] Code generation completed!')
 
+    except OtterAPIError as e:
+        error_console.print(f'[red]Error:[/red] {e.message}')
+        if debug:
+            traceback.print_exc()
+        raise typer.Exit(1)
     except Exception as e:
-        console.print(f'[red]Error:[/red] {str(e)}')
+        error_console.print(f'[red]Error:[/red] {str(e)}')
+        if debug:
+            traceback.print_exc()
         raise typer.Exit(1)
 
 
+@app.command()
+def init(
+    path: Annotated[
+        str, typer.Argument(help='Path for the configuration file')
+    ] = 'otter.yml',
+    force: Annotated[
+        bool, typer.Option('--force', '-f', help='Overwrite existing file')
+    ] = False,
+) -> None:
+    """Create a new configuration file interactively.
+
+    This command guides you through creating an OtterAPI configuration file
+    with all the necessary settings.
+
+    Examples:
+        otterapi init
+        otterapi init otter.yaml
+        otterapi init config.json --force
+    """
+    config_path = Path(path)
+
+    # Check if file exists
+    if config_path.exists() and not force:
+        error_console.print(
+            f'[red]Error:[/red] File {config_path} already exists. Use --force to overwrite.'
+        )
+        raise typer.Exit(1)
+
+    console.print(Panel('[bold]OtterAPI Configuration Setup[/bold]'))
+
+    # Get source
+    source = typer.prompt(
+        '\nOpenAPI specification source (URL or file path)',
+        default='https://petstore3.swagger.io/api/v3/openapi.json',
+    )
+
+    # Get output directory
+    output = typer.prompt('Output directory for generated code', default='./client')
+
+    # Get models file name
+    models_file = typer.prompt('Models file name', default='models.py')
+
+    # Get endpoints file name
+    endpoints_file = typer.prompt('Endpoints file name', default='endpoints.py')
+
+    # Build config
+    config_data = {
+        'documents': [
+            {
+                'source': source,
+                'output': output,
+                'models_file': models_file,
+                'endpoints_file': endpoints_file,
+            }
+        ]
+    }
+
+    # Ask if they want to add more documents
+    while typer.confirm('\nAdd another document?', default=False):
+        source = typer.prompt('OpenAPI specification source')
+        output = typer.prompt('Output directory')
+        config_data['documents'].append({'source': source, 'output': output})
+
+    # Write config file
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if path.endswith('.json'):
+        content = json.dumps(config_data, indent=2)
+    else:
+        content = yaml.dump(config_data, default_flow_style=False, sort_keys=False)
+
+    config_path.write_text(content)
+
+    console.print(f'\n[green]✓[/green] Configuration saved to {config_path}')
+    console.print('\n[dim]Preview:[/dim]')
+    syntax = Syntax(content, 'yaml' if not path.endswith('.json') else 'json')
+    console.print(syntax)
+
+    console.print(
+        f'\n[dim]Run [bold]otterapi generate -c {path}[/bold] to generate code.[/dim]'
+    )
+
+
+@app.command()
+def validate(
+    source: Annotated[str, typer.Argument(help='Path or URL to OpenAPI specification')],
+    verbose: Annotated[
+        bool, typer.Option('--verbose', '-v', help='Show detailed schema information')
+    ] = False,
+) -> None:
+    """Validate an OpenAPI specification.
+
+    This command loads and validates an OpenAPI specification without
+    generating any code, reporting any errors or warnings found.
+
+    Examples:
+        otterapi validate ./api.yaml
+        otterapi validate https://api.example.com/openapi.json
+        otterapi validate ./api.yaml --verbose
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn('[progress.description]{task.description}'),
+        console=console,
+    ) as progress:
+        task = progress.add_task(f'Loading {source}...', total=None)
+
+        try:
+            loader = SchemaLoader()
+            schema = loader.load(source)
+            progress.update(task, description='Validating schema...')
+
+            # Collect validation info
+            warnings: list[str] = []
+            info: dict[str, any] = {}
+
+            if schema.info:
+                info['title'] = schema.info.title
+                info['version'] = schema.info.version
+                if schema.info.description:
+                    info['description'] = (
+                        schema.info.description[:200] + '...'
+                        if len(schema.info.description or '') > 200
+                        else schema.info.description
+                    )
+
+            if schema.paths:
+                info['paths'] = len(schema.paths.root)
+
+                # Count operations
+                operations = 0
+                for path_item in schema.paths.root.values():
+                    for method in [
+                        'get',
+                        'post',
+                        'put',
+                        'patch',
+                        'delete',
+                        'head',
+                        'options',
+                    ]:
+                        if getattr(path_item, method, None):
+                            operations += 1
+                info['operations'] = operations
+
+            if schema.components:
+                if schema.components.schemas:
+                    info['schemas'] = len(schema.components.schemas)
+                if schema.components.securitySchemes:
+                    info['security_schemes'] = len(schema.components.securitySchemes)
+
+            # Check for potential issues
+            if schema.paths:
+                for path, path_item in schema.paths.root.items():
+                    for method in ['get', 'post', 'put', 'patch', 'delete']:
+                        operation = getattr(path_item, method, None)
+                        if operation and not operation.operationId:
+                            warnings.append(
+                                f'{method.upper()} {path}: Missing operationId'
+                            )
+
+            progress.update(task, description='Validation complete!')
+
+        except SchemaLoadError as e:
+            progress.stop()
+            error_console.print(f'[red]✗ Failed to load schema:[/red] {e.message}')
+            raise typer.Exit(1)
+        except SchemaValidationError as e:
+            progress.stop()
+            error_console.print(f'[red]✗ Schema validation failed:[/red] {e.message}')
+            raise typer.Exit(1)
+        except Exception as e:
+            progress.stop()
+            error_console.print(f'[red]✗ Error:[/red] {str(e)}')
+            raise typer.Exit(1)
+
+    # Print results
+    console.print(f'\n[green]✓[/green] Schema is valid: {source}\n')
+
+    if verbose or info:
+        table = Table(title='Schema Information')
+        table.add_column('Property', style='cyan')
+        table.add_column('Value')
+
+        for key, value in info.items():
+            table.add_row(key.replace('_', ' ').title(), str(value))
+
+        console.print(table)
+
+    if warnings:
+        console.print(f'\n[yellow]⚠ {len(warnings)} warning(s):[/yellow]')
+        for warning in warnings[:10]:  # Show first 10
+            console.print(f'  - {warning}')
+        if len(warnings) > 10:
+            console.print(f'  ... and {len(warnings) - 10} more')
+
+
 @app.command()
 def version() -> None:
-    """Show the version of otterapi."""
+    """Show the version of OtterAPI."""
+    try:
+        from otterapi._version import version as ver
+
+        console.print(f'otterapi version: [bold]{ver}[/bold]')
+    except ImportError:
+        console.print('otterapi version: [dim]unknown (development)[/dim]')
+
+    # Show dependency versions if verbose
+    console.print('\n[dim]Dependencies:[/dim]')
+    try:
+        import pydantic
+
+        console.print(f'  pydantic: {pydantic.__version__}')
+    except ImportError:
+        pass
+    try:
+        import httpx
+
+        console.print(f'  httpx: {httpx.__version__}')
+    except ImportError:
+        pass
     try:
-        from otterapi._version import version
+        import typer
 
-        console.print(f'otterapi version: {version}')
+        console.print(f'  typer: {typer.__version__}')
     except ImportError:
-        console.print('otterapi version: unknown')
+        pass
 
 
 if __name__ == '__main__':
-    generate()
+    app()

otterapi/codegen/__init__.py

@@ -0,0 +1,115 @@
+"""Code generation module for OtterAPI.
+
+This module provides the core code generation functionality for creating
+Python client code from OpenAPI specifications.
+
+Main Components:
+    - Codegen: The main orchestrator for code generation
+    - TypeGenerator: Generates Pydantic models from OpenAPI schemas
+    - SchemaLoader: Loads OpenAPI schemas from URLs or files
+    - SchemaResolver: Resolves $ref references in schemas
+    - TypeRegistry: Manages generated types and their dependencies
+    - CodeEmitter: Handles output of generated code
+
+Example:
+    >>> from otterapi.codegen import Codegen
+    >>> from otterapi.config import DocumentConfig
+    >>>
+    >>> config = DocumentConfig(
+    ...     source="./openapi.json",
+    ...     output="./client"
+    ... )
+    >>> codegen = Codegen(config)
+    >>> codegen.generate()
+"""
+
+from otterapi.codegen.ast_utils import ImportCollector
+from otterapi.codegen.codegen import Codegen
+
+# Re-export from dataframes module
+from otterapi.codegen.dataframes import (
+    DataFrameMethodConfig,
+    generate_dataframe_module,
+    get_dataframe_config_for_endpoint,
+)
+from otterapi.codegen.emitter import CodeEmitter, FileEmitter, StringEmitter
+
+# Re-export from endpoints module
+from otterapi.codegen.endpoints import (
+    DataFrameLibrary,
+    EndpointFunctionConfig,
+    EndpointFunctionFactory,
+    EndpointMode,
+    FunctionSignature,
+    FunctionSignatureBuilder,
+    ParameterASTBuilder,
+)
+from otterapi.codegen.schema import SchemaLoader, SchemaResolver
+
+# Re-export from splitting module
+from otterapi.codegen.splitting import (
+    EmittedModule,
+    ModuleMapResolver,
+    ModuleTree,
+    ModuleTreeBuilder,
+    ResolvedModule,
+    SplitModuleEmitter,
+    build_module_tree,
+)
+from otterapi.codegen.types import (
+    Endpoint,
+    ModelNameCollector,
+    Parameter,
+    RequestBodyInfo,
+    ResponseInfo,
+    Type,
+    TypeGenerator,
+    TypeInfo,
+    TypeRegistry,
+    collect_used_model_names,
+)
+
+__all__ = [
+    # Main codegen class
+    'Codegen',
+    # Type generation
+    'TypeGenerator',
+    'Type',
+    'TypeRegistry',
+    'TypeInfo',
+    'ModelNameCollector',
+    'collect_used_model_names',
+    # Schema handling
+    'SchemaLoader',
+    'SchemaResolver',
+    # Endpoint types
+    'Endpoint',
+    'Parameter',
+    'RequestBodyInfo',
+    'ResponseInfo',
+    # Code emission
+    'CodeEmitter',
+    'FileEmitter',
+    'StringEmitter',
+    'ImportCollector',
+    # Endpoint building
+    'EndpointFunctionConfig',
+    'EndpointFunctionFactory',
+    'EndpointMode',
+    'DataFrameLibrary',
+    'FunctionSignature',
+    'FunctionSignatureBuilder',
+    'ParameterASTBuilder',
+    # DataFrame utilities
+    'DataFrameMethodConfig',
+    'generate_dataframe_module',
+    'get_dataframe_config_for_endpoint',
+    # Module splitting
+    'ModuleTree',
+    'ModuleTreeBuilder',
+    'ModuleMapResolver',
+    'ResolvedModule',
+    'EmittedModule',
+    'SplitModuleEmitter',
+    'build_module_tree',
+]

otterapi/codegen/ast_utils.py

@@ -1,9 +1,33 @@
+"""AST utilities and import collection for code generation.
+
+This module provides helper functions for building Python AST nodes
+and utilities for collecting and organizing imports during code generation.
+"""
+
 import ast
 import keyword
 from collections.abc import Iterable
 
 PYTHON_KEYWORDS = set(keyword.kwlist)
 
+__all__ = [
+    # AST helpers
+    '_name',
+    '_attr',
+    '_subscript',
+    '_union_expr',
+    '_optional_expr',
+    '_argument',
+    '_assign',
+    '_import',
+    '_call',
+    '_func',
+    '_async_func',
+    '_all',
+    # Import collection
+    'ImportCollector',
+]
+
 
 def _name(name: str) -> ast.Name:
     return ast.Name(id=name, ctx=ast.Load())
@@ -11,17 +35,27 @@ def _name(name: str) -> ast.Name:
 
 def _attr(value: str | ast.expr, attr: str) -> ast.Attribute:
     return ast.Attribute(
-        value=_name(value) if isinstance(value, str) else value, attr=attr
+        value=_name(value) if isinstance(value, str) else value,
+        attr=attr,
+        ctx=ast.Load(),
     )
 
 
 def _subscript(generic: str, inner: ast.expr) -> ast.Subscript:
-    return ast.Subscript(value=_name(generic), slice=inner)
+    return ast.Subscript(value=_name(generic), slice=inner, ctx=ast.Load())
 
 
-def _union_expr(types: list[ast.expr]) -> ast.Subscript:
-    # Union[A, B, C]
-    return _subscript('Union', ast.Tuple(elts=types))
+def _union_expr(types: list[ast.expr]) -> ast.expr:
+    # A | B | C (using pipe operator instead of Union[A, B, C])
+    if not types:
+        raise ValueError('_union_expr requires at least one type')
+    if len(types) == 1:
+        return types[0]
+    # Build a chain of BinOp with BitOr: A | B | C
+    result = types[0]
+    for t in types[1:]:
+        result = ast.BinOp(left=result, op=ast.BitOr(), right=t)
+    return result
 
 
 def _optional_expr(inner: ast.expr) -> ast.Subscript:
@@ -36,6 +70,12 @@ def _argument(name: str, value: ast.expr | None = None) -> ast.arg:
 
 
 def _assign(target: ast.expr, value: ast.expr) -> ast.Assign:
+    # Ensure target has Store context
+    if isinstance(target, ast.Name):
+        target = ast.Name(id=target.id, ctx=ast.Store())
+    elif isinstance(target, ast.Attribute):
+        # For attributes, only the outermost needs Store context
+        target.ctx = ast.Store()
     return ast.Assign(
         targets=[target],
         value=value,
@@ -119,3 +159,92 @@ def _all(names: Iterable[str]) -> ast.Assign:
             elts=[ast.Constant(value=name) for name in names], ctx=ast.Load()
         ),
     )
+
+
+# =============================================================================
+# Import Collection
+# =============================================================================
+
+
+class ImportCollector:
+    """Collects and manages imports for generated Python code.
+
+    This class provides a centralized way to collect imports from various
+    sources during code generation and convert them to AST import statements.
+    It automatically deduplicates imports and sorts them for consistent output.
+
+    Example:
+        >>> collector = ImportCollector()
+        >>> collector.add_imports({'typing': {'List', 'Dict'}})
+        >>> collector.add_imports({'typing': {'Optional'}})
+        >>> imports = collector.to_ast()
+        >>> # Returns [ImportFrom(module='typing', names=['Dict', 'List', 'Optional'])]
+    """
+
+    def __init__(self):
+        """Initialize an empty import collector."""
+        self._imports: dict[str, set[str]] = {}
+
+    def add_imports(self, imports: dict[str, set[str]]) -> None:
+        """Add imports from a dictionary mapping modules to sets of names.
+
+        Args:
+            imports: Dictionary mapping module names to sets of imported names.
+                    Example: {'typing': {'List', 'Dict'}, 'pydantic': {'BaseModel'}}
+        """
+        for module, names in imports.items():
+            if module not in self._imports:
+                self._imports[module] = set()
+            self._imports[module].update(names)
+
+    def add_import(self, module: str, name: str) -> None:
+        """Add a single import.
+
+        Args:
+            module: The module to import from (e.g., 'typing', 'pydantic').
+            name: The name to import (e.g., 'List', 'BaseModel').
+        """
+        if module not in self._imports:
+            self._imports[module] = set()
+        self._imports[module].add(name)
+
+    def to_ast(self, reverse_sort: bool = True) -> list[ast.ImportFrom]:
+        """Convert collected imports to AST ImportFrom statements.
+
+        Args:
+            reverse_sort: If True, sort modules in reverse order (default).
+                         This is useful for placing standard library imports last.
+
+        Returns:
+            List of ast.ImportFrom statements, sorted by module name.
+            Names within each import are also sorted alphabetically.
+        """
+        import_stmts = []
+        for module, names in sorted(self._imports.items(), reverse=reverse_sort):
+            import_stmt = ast.ImportFrom(
+                module=module,
+                names=[ast.alias(name=name, asname=None) for name in sorted(names)],
+                level=0,
+            )
+            import_stmts.append(import_stmt)
+        return import_stmts
+
+    def has_imports(self) -> bool:
+        """Check if any imports have been collected.
+
+        Returns:
+            True if imports exist, False otherwise.
+        """
+        return bool(self._imports)
+
+    def clear(self) -> None:
+        """Clear all collected imports."""
+        self._imports.clear()
+
+    def get_modules(self) -> set[str]:
+        """Get the set of all modules that have been imported.
+
+        Returns:
+            Set of module names.
+        """
+        return set(self._imports.keys())