otterapi 0.1.4__tar.gz → 0.1.6__tar.gz

{otterapi-0.1.4 → otterapi-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: otterapi
-Version: 0.1.4
+Version: 0.1.6
 Summary: A cute little companion that generates type-safe clients from OpenAPI documents.
 Project-URL: Source, https://github.com/danplischke/otter
 Author: Dan Plischke

{otterapi-0.1.4 → otterapi-0.1.6}/otterapi/codegen/codegen.py

@@ -74,6 +74,59 @@ def _load_models_mixin_source() -> str:
     )
 
 
+def _topo_sort_by_base_classes(
+    types_list: list,
+    model_names: set[str],
+) -> list:
+    """Return *types_list* re-ordered so every base class precedes its subclasses.
+
+    ``get_sorted_types()`` uses field-level dependency edges.  When it breaks a
+    field-level cycle it may place a subclass before its base class.
+    ``from __future__ import annotations`` defers annotation evaluation, so
+    field-level cycles are fine — but ``class Foo(Bar):`` base expressions are
+    evaluated *eagerly* at class-definition time.  Inheritance always forms a
+    DAG in Python (cycles are a ``TypeError``), so a simple DFS topological sort
+    on base-class edges always terminates and produces a valid ordering.
+
+    Types with no name (primitive aliases, etc.) are appended unchanged after
+    the named types.
+    """
+    name_to_type: dict[str, object] = {t.name: t for t in types_list if t.name}
+
+    def base_deps(t: object) -> set[str]:
+        impl = t.implementation_ast  # type: ignore[attr-defined]
+        if not isinstance(impl, ast.ClassDef):
+            return set()
+        return {
+            b.id for b in impl.bases if isinstance(b, ast.Name) and b.id in model_names
+        }
+
+    result: list = []
+    visited: set[str] = set()
+
+    def dfs(name: str) -> None:
+        if name in visited:
+            return
+        visited.add(name)
+        t = name_to_type.get(name)
+        if t is None:
+            return
+        for base_name in base_deps(t):
+            dfs(base_name)
+        result.append(t)
+
+    for t in types_list:
+        if t.name:
+            dfs(t.name)
+
+    # Preserve unnamed entries (should be rare / none for ClassDef models)
+    for t in types_list:
+        if not t.name:
+            result.append(t)
+
+    return result
+
+
 # Content types that should be treated as JSON
 JSON_CONTENT_TYPES = {MediaType.JSON, MediaType.TEXT_JSON}
 
@@ -1159,6 +1212,7 @@ class Codegen(OpenAPIProcessor):
                 is_async=is_async,
                 default_format=default_format,
                 default_batch_size=self.config.export.batch_size,
+                pagination_limit_param=self.config.pagination.limit_param,
             )
             endpoint_names.add(fn_name)
             body.append(fn)
@@ -1218,7 +1272,12 @@ class Codegen(OpenAPIProcessor):
         """Emit sync+async export wrappers for a non-paginated list endpoint."""
         if not self.config.export.enabled:
             return False
-        item_type_ast, item_type_imports = self._get_item_type_ast(endpoint)
+        # When response unwrapping is active, the list lives behind the data
+        # path (e.g. envelope.data) rather than directly on the response type,
+        # so resolve the item type through that path.
+        should_unwrap, unwrap_path = self._get_unwrap_config(endpoint)
+        data_path = unwrap_path if should_unwrap else None
+        item_type_ast, item_type_imports = self._get_item_type_ast(endpoint, data_path)
         if item_type_ast is None:
             return False
         should_generate, formats, _path = (
@@ -1311,23 +1370,63 @@ class Codegen(OpenAPIProcessor):
         import_collector = ImportCollector()
         all_names = set()
 
-        for type_name, type_ in self.typegen.types.items():
+        # Names of all types that will get _HtmlReprMixin injected.  Used
+        # below to skip re-injection for classes whose base is already a
+        # generated model (which would cause an MRO conflict).
+        all_model_names: set[str] = {
+            type_.name
+            for type_ in self.typegen.types.values()
+            if type_.name and isinstance(type_.implementation_ast, ast.ClassDef)
+        }
+
+        # Emit types in dependency order (dependencies before dependents) so
+        # that forward references in field annotations resolve at class-creation
+        # time.  get_sorted_types() returns dependents-first; reversing gives
+        # the dependencies-first order needed for correct emission.
+        # Types not reachable from get_sorted_types (e.g. orphaned names) are
+        # appended at the end via the seen-set guard.
+        sorted_types = list(reversed(self.typegen.get_sorted_types()))
+        seen: set[str] = {t.name for t in sorted_types if t.name}
+        for extra in self.typegen.types.values():
+            if extra.name not in seen:
+                sorted_types.append(extra)
+
+        # Re-sort to guarantee every base class precedes every subclass.
+        # get_sorted_types() uses field-level dependencies; when it breaks a
+        # field-level cycle it may place a subclass before its base class.
+        # from __future__ import annotations makes field-type annotations lazy,
+        # but base classes in `class Foo(Base):` are evaluated EAGERLY, so the
+        # ordering of ClassDef nodes in the emitted file must respect the
+        # inheritance DAG.  Python forbids inheritance cycles, so this sort
+        # always terminates.
+        sorted_types = _topo_sort_by_base_classes(sorted_types, all_model_names)
+
+        for type_ in sorted_types:
             if type_.implementation_ast:
                 impl = type_.implementation_ast
                 # Inject _HtmlReprMixin as the first base of every model class so
                 # it renders as an HTML table in Jupyter without touching the
                 # per-model implementation_ast (which is exec'd in unit tests).
+                # Skip injection when a base is itself a generated model: that
+                # base already gets _HtmlReprMixin, so adding it again would
+                # produce an unresolvable MRO (e.g. Child(_HtmlReprMixin, Parent)
+                # where Parent is already Child(_HtmlReprMixin, BaseModel)).
                 if isinstance(impl, ast.ClassDef):
-                    impl = ast.ClassDef(
-                        name=impl.name,
-                        bases=[
-                            ast.Name(id='_HtmlReprMixin', ctx=ast.Load()),
-                            *impl.bases,
-                        ],
-                        keywords=impl.keywords,
-                        body=impl.body,
-                        decorator_list=impl.decorator_list,
+                    has_model_base = any(
+                        isinstance(b, ast.Name) and b.id in all_model_names
+                        for b in impl.bases
                     )
+                    if not has_model_base:
+                        impl = ast.ClassDef(
+                            name=impl.name,
+                            bases=[
+                                ast.Name(id='_HtmlReprMixin', ctx=ast.Load()),
+                                *impl.bases,
+                            ],
+                            keywords=impl.keywords,
+                            body=impl.body,
+                            decorator_list=impl.decorator_list,
+                        )
                 body.append(impl)
                 if type_.name:
                     all_names.add(type_.name)
@@ -1336,6 +1435,41 @@ class Codegen(OpenAPIProcessor):
                 import_collector.add_imports(type_.implementation_imports)
                 import_collector.add_imports(type_.annotation_imports)
 
+        # Emit model_rebuild() / update_forward_refs() for cyclic models so
+        # that Pydantic can resolve the forward references introduced by
+        # from __future__ import annotations and self-referential schemas.
+        cyclic = getattr(self.typegen, '_cyclic', set())
+        for model_name in sorted(cyclic):
+            if model_name in all_names:
+                if self.typegen.pydantic_version == 1:
+                    body.append(
+                        ast.Expr(
+                            ast.Call(
+                                func=ast.Attribute(
+                                    value=ast.Name(id=model_name, ctx=ast.Load()),
+                                    attr='update_forward_refs',
+                                    ctx=ast.Load(),
+                                ),
+                                args=[],
+                                keywords=[],
+                            )
+                        )
+                    )
+                else:
+                    body.append(
+                        ast.Expr(
+                            ast.Call(
+                                func=ast.Attribute(
+                                    value=ast.Name(id=model_name, ctx=ast.Load()),
+                                    attr='model_rebuild',
+                                    ctx=ast.Load(),
+                                ),
+                                args=[],
+                                keywords=[],
+                            )
+                        )
+                    )
+
         # Prepend the _HtmlReprMixin helper (defines _repr_html_ for Jupyter)
         body[0:0] = ast.parse(_load_models_mixin_source()).body
 
@@ -1346,6 +1480,19 @@ class Codegen(OpenAPIProcessor):
         for import_stmt in import_collector.to_ast():
             body.insert(0, import_stmt)
 
+        # from __future__ import annotations must be the very first statement
+        # so forward references in type annotations resolve lazily.  This is
+        # required when cyclic models refer to each other before their class
+        # bodies are fully defined.
+        body.insert(
+            0,
+            ast.ImportFrom(
+                module='__future__',
+                names=[ast.alias(name='annotations')],
+                level=0,
+            ),
+        )
+
         write_mod(body, path)
 
     def generate(self):
@@ -1721,8 +1868,20 @@ class Codegen(OpenAPIProcessor):
 
         Note:
             This method delegates to get_dataframe_config_for_endpoint() from dataframe_utils.
+            When response unwrapping is active, the unwrapped data type is the
+            endpoint's real return type, so it is passed through for list
+            detection -- otherwise non-paginated envelope list endpoints (e.g.
+            ``ResponseWithStatusEnvelope*``) would be misclassified and lose
+            their DataFrame variants.
         """
-        return get_dataframe_config_for_endpoint(endpoint, self.config.dataframe)
+        unwrap_type_ast = None
+        should_unwrap, unwrap_path = self._get_unwrap_config(endpoint)
+        if should_unwrap and unwrap_path:
+            unwrap_type_ast, _ = self._get_unwrapped_type_ast(endpoint, unwrap_path)
+
+        return get_dataframe_config_for_endpoint(
+            endpoint, self.config.dataframe, unwrap_type_ast=unwrap_type_ast
+        )
 
     def _get_pagination_config(
         self, endpoint: Endpoint

{otterapi-0.1.4 → otterapi-0.1.6}/otterapi/codegen/dataframes.py

@@ -26,6 +26,7 @@ __all__ = [
     'get_dataframe_config_from_parts',
     'endpoint_returns_list',
     'response_type_returns_list',
+    'annotation_ast_returns_list',
 ]
 
 
@@ -79,14 +80,46 @@ class DataFrameMethodConfig:
     path: str | None = None
 
 
-def endpoint_returns_list(endpoint: 'Endpoint') -> bool:
+def annotation_ast_returns_list(annotation_ast: 'ast.expr | None') -> bool:
+    """Check if a raw annotation AST represents a ``list[...]`` type.
+
+    Args:
+        annotation_ast: The annotation AST node to check, or None.
+
+    Returns:
+        True if the annotation is a ``list[...]`` subscript, False otherwise.
+    """
+    if isinstance(annotation_ast, ast.Subscript):
+        if isinstance(annotation_ast.value, ast.Name) and (
+            annotation_ast.value.id == 'list'
+        ):
+            return True
+
+    return False
+
+
+def endpoint_returns_list(
+    endpoint: 'Endpoint',
+    unwrap_type_ast: 'ast.expr | None' = None,
+) -> bool:
     """Check if an endpoint returns a list type.
 
     Examines the endpoint's response type annotation AST to determine
     if it represents a list type.
 
+    When response unwrapping is active for the endpoint, the function's actual
+    return type is the unwrapped data field rather than the envelope model on
+    ``endpoint.response_type``. In that case the caller passes the unwrapped
+    type AST (e.g. ``list[Pet]`` extracted from ``data``) via
+    *unwrap_type_ast*, and it is consulted instead of the envelope type.
+    Without this, every non-paginated ``ResponseWithStatusEnvelope*`` list
+    endpoint would be misclassified as non-list and silently lose its
+    DataFrame variants.
+
     Args:
         endpoint: The endpoint to check.
+        unwrap_type_ast: The AST of the unwrapped return type when response
+            unwrapping is active, or None when it is not.
 
     Returns:
         True if the endpoint returns a list, False otherwise.
@@ -96,6 +129,9 @@ def endpoint_returns_list(endpoint: 'Endpoint') -> bool:
         >>> endpoint_returns_list(endpoint)
         True
     """
+    if unwrap_type_ast is not None:
+        return annotation_ast_returns_list(unwrap_type_ast)
+
     if not endpoint.response_type:
         return False
 
@@ -117,18 +153,13 @@ def response_type_returns_list(response_type: 'Type | None') -> bool:
     if not response_type:
         return False
 
-    if response_type.annotation_ast:
-        ann = response_type.annotation_ast
-        if isinstance(ann, ast.Subscript):
-            if isinstance(ann.value, ast.Name) and ann.value.id == 'list':
-                return True
-
-    return False
+    return annotation_ast_returns_list(response_type.annotation_ast)
 
 
 def get_dataframe_config_for_endpoint(
     endpoint: 'Endpoint',
     dataframe_config: 'DataFrameConfig',
+    unwrap_type_ast: 'ast.expr | None' = None,
 ) -> DataFrameMethodConfig:
     """Get the DataFrame method configuration for an endpoint.
 
@@ -139,6 +170,9 @@ def get_dataframe_config_for_endpoint(
     Args:
         endpoint: The endpoint to get configuration for.
         dataframe_config: The global DataFrame configuration.
+        unwrap_type_ast: The AST of the unwrapped return type when response
+            unwrapping is active for the endpoint, or None. When provided it
+            is used for list detection instead of the envelope response type.
 
     Returns:
         DataFrameMethodConfig with generation flags and default path.
@@ -151,8 +185,9 @@ def get_dataframe_config_for_endpoint(
     if not dataframe_config.enabled:
         return DataFrameMethodConfig()
 
-    # Check if this endpoint returns a list type
-    returns_list = endpoint_returns_list(endpoint)
+    # Check if this endpoint returns a list type. When response unwrapping is
+    # active the unwrapped data type is the real return type, so prefer it.
+    returns_list = endpoint_returns_list(endpoint, unwrap_type_ast=unwrap_type_ast)
 
     # Get the sync function name for config lookup
     endpoint_name = endpoint.sync_fn_name

{otterapi-0.1.4 → otterapi-0.1.6}/otterapi/codegen/endpoints.py

@@ -227,10 +227,18 @@ class FunctionSignatureBuilder:
             if param.required:
                 self._args.append(arg)
             else:
-                # Wrap annotation in `| None` so the `= None` default is type-safe.
-                optional_annotation = _union_expr(
-                    [annotation, ast.Constant(value=None)]
-                )
+                # Wrap annotation in `| None` only if not already nullable.
+                # The OpenAPI schema may already encode nullability (nullable:true
+                # or type:[..., null]), in which case schema_to_type emits
+                # `T | None` and we must not add a second `| None`.
+                from otterapi.codegen.types import _binop_includes_none
+
+                if _binop_includes_none(annotation):
+                    optional_annotation = annotation
+                else:
+                    optional_annotation = _union_expr(
+                        [annotation, ast.Constant(value=None)]
+                    )
                 self._kwonlyargs.append(
                     _argument(param.name_sanitized, optional_annotation)
                 )

{otterapi-0.1.4 → otterapi-0.1.6}/otterapi/codegen/export.py

@@ -99,9 +99,20 @@ class ExportMethodConfig:
             self.formats = []
 
 
-def _returns_list(response_type: 'Type | None') -> bool:
+def _returns_list(
+    response_type: 'Type | None',
+    unwrap_type_ast: 'ast.expr | None' = None,
+) -> bool:
     # Local import avoids a circular dependency at module load.
-    from otterapi.codegen.dataframes import response_type_returns_list
+    from otterapi.codegen.dataframes import (
+        annotation_ast_returns_list,
+        response_type_returns_list,
+    )
+
+    # When response unwrapping is active, list detection must inspect the
+    # unwrapped type (e.g. ``list[Thing]``) rather than the envelope type.
+    if unwrap_type_ast is not None:
+        return annotation_ast_returns_list(unwrap_type_ast)
 
     return response_type_returns_list(response_type)
 
@@ -109,12 +120,13 @@ def _returns_list(response_type: 'Type | None') -> bool:
 def get_export_config_for_endpoint(
     endpoint: 'Endpoint',
     export_config: 'ExportConfig',
+    unwrap_type_ast: 'ast.expr | None' = None,
 ) -> ExportMethodConfig:
     """Resolve export configuration for a fully-constructed endpoint."""
     if not export_config.enabled:
         return ExportMethodConfig()
 
-    returns_list = _returns_list(endpoint.response_type)
+    returns_list = _returns_list(endpoint.response_type, unwrap_type_ast)
     should_generate, formats, path = export_config.should_generate_for_endpoint(
         endpoint_name=endpoint.sync_fn_name,
         returns_list=returns_list,
@@ -188,8 +200,8 @@ def _format_literal_annotation() -> ast.expr:
 
 
 def _output_path_annotation() -> ast.expr:
-    """Build the AST for ``str | Path | None`` (the wrapper's path argument type)."""
-    return _union_expr([_name('str'), _name('Path'), ast.Constant(value=None)])
+    """Build the AST for ``str | Path | UPath`` (the wrapper's path argument type)."""
+    return _union_expr([_name('str'), _name('Path'), _name('UPath')])
 
 
 def _add_export_kwonly_args(
@@ -199,9 +211,6 @@ def _add_export_kwonly_args(
     default_batch_size: int,
 ) -> None:
     """Append the export-specific keyword-only args + defaults in place."""
-    kwonlyargs.append(_argument('output_path', _output_path_annotation()))
-    kw_defaults.append(ast.Constant(value=None))  # required at call time
-
     kwonlyargs.append(_argument('format', _format_literal_annotation()))
     kw_defaults.append(ast.Constant(value=default_format))
 
@@ -300,6 +309,9 @@ def _build_export_function(
     from otterapi.codegen.endpoints import FunctionSignatureBuilder
 
     builder = FunctionSignatureBuilder()
+    # output_path is the first positional argument so it can be passed
+    # without a keyword: export_fn("out.jsonl", symbol="BRCA1")
+    builder._args.append(_argument('output_path', _output_path_annotation()))
     builder.add_parameters(parameters)
     builder.add_request_body(request_body_info)
     builder.add_client_parameter()
@@ -370,6 +382,7 @@ def _build_export_function(
 
     imports: ImportDict = {
         'pathlib': {'Path'},
+        'upath': {'UPath'},
         'typing': {'Any', 'Literal'},
         '._export': {'export_async' if (is_async and is_paginated) else 'export'},
     }
@@ -428,6 +441,7 @@ def build_standalone_paginated_export_fn(
     is_async: bool,
     default_format: str = 'csv',
     default_batch_size: int = 1000,
+    pagination_limit_param: str = 'limit',
 ) -> tuple[ast.FunctionDef | ast.AsyncFunctionDef, ImportDict]:
     """Build an export wrapper around a paginated endpoint's ``_iter`` variant.
 
@@ -435,11 +449,21 @@ def build_standalone_paginated_export_fn(
     ``page_size``/``max_items`` (forwarded to the iter function), drives the
     iterator, and pipes items into ``export(...)`` (sync) or
     ``export_async(...)`` (async). Memory stays bounded by ``batch_size``.
+
+    The raw OpenAPI ``limit`` parameter (or ``pagination_limit_param``) is
+    intentionally excluded: the ``_iter`` function manages page size
+    internally via ``page_size`` / ``max_items``.
     """
+    # Strip the raw pagination limit param — the _iter fn handles it internally.
+    filtered_parameters = (
+        [p for p in parameters if p.name != pagination_limit_param]
+        if parameters
+        else parameters
+    )
     return _build_export_function(
         fn_name=fn_name,
         target_fn_name=target_iter_fn_name,
-        parameters=parameters,
+        parameters=filtered_parameters,
         request_body_info=request_body_info,
         item_type_ast=item_type_ast,
         item_type_imports=item_type_imports or {},

{otterapi-0.1.4 → otterapi-0.1.6}/otterapi/codegen/splitting.py

@@ -1019,7 +1019,19 @@ class SplitModuleEmitter:
         if not (self.dataframe_config and self.dataframe_config.enabled):
             return False
 
-        df_config = get_dataframe_config_for_endpoint(endpoint, self.dataframe_config)
+        # When response unwrapping is active the unwrapped data type is the
+        # endpoint's real return type, so feed it to list detection -- without
+        # this, non-paginated envelope list endpoints (e.g.
+        # ``ResponseWithStatusEnvelope*``) are misclassified as non-list and
+        # silently lose their DataFrame variants.
+        unwrap_type_ast = None
+        should_unwrap, unwrap_path = self._get_unwrap_config(endpoint)
+        if should_unwrap and unwrap_path:
+            unwrap_type_ast, _ = self._get_unwrapped_type_ast(endpoint, unwrap_path)
+
+        df_config = get_dataframe_config_for_endpoint(
+            endpoint, self.dataframe_config, unwrap_type_ast=unwrap_type_ast
+        )
 
         generated = False
         if df_config.generate_pandas:
@@ -1109,7 +1121,12 @@ class SplitModuleEmitter:
         """Emit sync+async export wrappers for a non-paginated list endpoint."""
         if not self.export_config or not self.export_config.enabled:
             return False
-        item_type_ast, item_type_imports = self._get_item_type_ast(endpoint)
+        # When response unwrapping is active, the list lives behind the data
+        # path (e.g. envelope.data) rather than directly on the response type,
+        # so resolve the item type through that path.
+        should_unwrap, unwrap_path = self._get_unwrap_config(endpoint)
+        data_path = unwrap_path if should_unwrap else None
+        item_type_ast, item_type_imports = self._get_item_type_ast(endpoint, data_path)
         if item_type_ast is None:
             return False
         should_generate, formats, _path = (
@@ -1322,6 +1339,18 @@ class SplitModuleEmitter:
         final_body.append(_all(sorted(all_names)))
         final_body.extend(body)
 
+        # Prepend from __future__ import annotations so forward references in
+        # type annotations (e.g. model names imported from .models) resolve
+        # correctly when models contain cyclic references.
+        final_body.insert(
+            0,
+            ast.ImportFrom(
+                module='__future__',
+                names=[ast.alias(name='annotations')],
+                level=0,
+            ),
+        )
+
         file_path = UPath(file_path)
         file_path.parent.mkdir(parents=True, exist_ok=True)
         write_mod(final_body, file_path)