python-openapi 0.1.8__tar.gz → 0.1.10__tar.gz

{python-openapi-0.1.8 → python_openapi-0.1.10}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2022 Levente Hunyadi
+Copyright (c) 2021-2025 Levente Hunyadi
 Copyright (c) 2021-2022 Instructure Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

{python-openapi-0.1.8 → python_openapi-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-openapi
-Version: 0.1.8
+Version: 0.1.10
 Summary: Generate an OpenAPI specification from a Python class definition
 Home-page: https://github.com/hunyadi/pyopenapi
 Author: Levente Hunyadi
@@ -15,11 +15,16 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: aiohttp>=3.11
+Requires-Dist: json_strong_typing>=0.3.7
 
 # Generate an OpenAPI specification from a Python class
 

{python-openapi-0.1.8 → python_openapi-0.1.10}/pyopenapi/__init__.py

@@ -1,10 +1,10 @@
-from typing import Any, Callable, Optional, TypeVar
+from typing import Any, Callable, List, Optional, TypeVar
 
 from .metadata import WebMethod
-from .options import *
-from .utility import Specification
+from .options import *  # noqa: F403
+from .utility import Specification as Specification
 
-__version__ = "0.1.8"
+__version__ = "0.1.10"
 
 T = TypeVar("T")
 
@@ -29,13 +29,9 @@ def webmethod(
     """
 
     if request_example is not None and request_examples is not None:
-        raise ValueError(
-            "arguments `request_example` and `request_examples` are exclusive"
-        )
+        raise ValueError("arguments `request_example` and `request_examples` are exclusive")
     if response_example is not None and response_examples is not None:
-        raise ValueError(
-            "arguments `response_example` and `response_examples` are exclusive"
-        )
+        raise ValueError("arguments `response_example` and `response_examples` are exclusive")
 
     if request_example:
         request_examples = [request_example]

{python-openapi-0.1.8 → python_openapi-0.1.10}/pyopenapi/generator.py

@@ -1,31 +1,20 @@
-from typing import Any, Dict, Set, Union
+import dataclasses
+import hashlib
+import ipaddress
+import typing
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple, Union
 
 from strong_typing.core import JsonType
-from strong_typing.docstring import parse_type
-from strong_typing.inspection import (
-    is_generic_list,
-    is_type_optional,
-    is_type_union,
-    unwrap_generic_list,
-    unwrap_optional_type,
-    unwrap_union_types,
-)
+from strong_typing.docstring import Docstring, parse_type
+from strong_typing.inspection import is_generic_list, is_type_optional, is_type_union, unwrap_generic_list, unwrap_optional_type, unwrap_union_types
 from strong_typing.name import python_type_to_name
-from strong_typing.schema import (
-    JsonSchemaGenerator,
-    Schema,
-    SchemaOptions,
-    get_schema_identifier,
-)
-from strong_typing.serialization import object_to_json
+from strong_typing.schema import JsonSchemaGenerator, Schema, SchemaOptions, get_schema_identifier, register_schema
+from strong_typing.serialization import json_dump_string, object_to_json
 
-from .operations import (
-    EndpointOperation,
-    HTTPMethod,
-    get_endpoint_events,
-    get_endpoint_operations,
-)
-from .options import *
+from .operations import EndpointOperation, HTTPMethod, get_endpoint_events, get_endpoint_operations
+from .options import HTTPStatusCode, Options
 from .specification import (
     Components,
     Document,
@@ -39,13 +28,39 @@ from .specification import (
     RequestBody,
     Response,
     ResponseRef,
+    SchemaOrRef,
     SchemaRef,
     Tag,
     TagGroup,
 )
 
+register_schema(
+    ipaddress.IPv4Address,
+    schema={
+        "type": "string",
+        "format": "ipv4",
+        "title": "IPv4 address",
+        "description": "IPv4 address, according to dotted-quad ABNF syntax as defined in RFC 2673, section 3.2.",
+    },
+    examples=["192.0.2.0", "198.51.100.1", "203.0.113.255"],
+)
 
-SchemaOrRef = Union[Schema, SchemaRef]
+register_schema(
+    ipaddress.IPv6Address,
+    schema={
+        "type": "string",
+        "format": "ipv6",
+        "title": "IPv6 address",
+        "description": "IPv6 address, as defined in RFC 2373, section 2.2.",
+    },
+    examples=[
+        "FEDC:BA98:7654:3210:FEDC:BA98:7654:3210",
+        "1080:0:0:0:8:800:200C:417A",
+        "1080::8:800:200C:417A",
+        "FF01::101",
+        "::1",
+    ],
+)
 
 
 def http_status_to_string(status_code: HTTPStatusCode) -> str:
@@ -135,9 +150,7 @@ class ContentBuilder:
         self.schema_transformer = schema_transformer
         self.sample_transformer = sample_transformer
 
-    def build_content(
-        self, payload_type: type, examples: Optional[List[Any]] = None
-    ) -> Dict[str, MediaType]:
+    def build_content(self, payload_type: type, examples: Optional[List[Any]] = None) -> Dict[str, MediaType]:
         "Creates the content subtree for a request or response."
 
         if is_generic_list(payload_type):
@@ -149,35 +162,75 @@ class ContentBuilder:
 
         return {media_type: self.build_media_type(item_type, examples)}
 
-    def build_media_type(
-        self, item_type: type, examples: Optional[List[Any]] = None
-    ) -> MediaType:
-
+    def build_media_type(self, item_type: type, examples: Optional[List[Any]] = None) -> MediaType:
         schema = self.schema_builder.classdef_to_ref(item_type)
         if self.schema_transformer:
-            schema_transformer: Callable[[SchemaOrRef], SchemaOrRef] = self.schema_transformer  # type: ignore
+            schema_transformer: Callable[[SchemaOrRef], SchemaOrRef] = self.schema_transformer
             schema = schema_transformer(schema)
+
+        if not examples:
+            return MediaType(schema=schema)
+
+        if len(examples) == 1:
+            return MediaType(schema=schema, example=self._build_example(examples[0]))
+
         return MediaType(
             schema=schema,
             examples=self._build_examples(examples),
         )
 
-    def _build_examples(
-        self, examples: Optional[List[Any]] = None
-    ) -> Optional[Dict[str, Union[Example, ExampleRef]]]:
+    def _build_examples(self, examples: List[Any]) -> Dict[str, Union[Example, ExampleRef]]:
+        "Creates a set of several examples for a media type."
+
+        builder = ExampleBuilder(self.sample_transformer)
+
+        results: Dict[str, Union[Example, ExampleRef]] = {}
+        for example in examples:
+            name, value = builder.get_named(example)
+            results[name] = Example(value=value)
+
+        return results
 
-        if examples is None:
-            return None
+    def _build_example(self, example: Any) -> Any:
+        "Creates a single example for a media type."
 
-        if self.sample_transformer:
-            sample_transformer: Callable[[JsonType], JsonType] = self.sample_transformer  # type: ignore
+        builder = ExampleBuilder(self.sample_transformer)
+        return builder.get_anonymous(example)
+
+
+class ExampleBuilder:
+    sample_transformer: Callable[[JsonType], JsonType]
+
+    def __init__(
+        self,
+        sample_transformer: Optional[Callable[[JsonType], JsonType]] = None,
+    ) -> None:
+        if sample_transformer:
+            self.sample_transformer = sample_transformer
         else:
-            sample_transformer = lambda sample: sample
+            self.sample_transformer = lambda sample: sample  # noqa: E731
+
+    def _get_value(self, example: Any) -> JsonType:
+        return self.sample_transformer(object_to_json(example))
+
+    def get_anonymous(self, example: Any) -> JsonType:
+        return self._get_value(example)
+
+    def get_named(self, example: Any) -> Tuple[str, JsonType]:
+        value = self._get_value(example)
+
+        name: Optional[str] = None
 
-        return {
-            str(example): Example(value=sample_transformer(object_to_json(example)))
-            for example in examples
-        }
+        if type(example).__str__ is not object.__str__:
+            friendly_name = str(example)
+            if friendly_name.isprintable():
+                name = friendly_name
+
+        if name is None:
+            hash_string = hashlib.md5(json_dump_string(value).encode("utf-8")).digest().hex()
+            name = f"ex-{hash_string}"
+
+        return name, value
 
 
 @dataclass
@@ -210,15 +263,11 @@ class ResponseBuilder:
     def __init__(self, content_builder: ContentBuilder) -> None:
         self.content_builder = content_builder
 
-    def _get_status_responses(
-        self, options: ResponseOptions
-    ) -> Dict[str, StatusResponse]:
+    def _get_status_responses(self, options: ResponseOptions) -> Dict[str, StatusResponse]:
         status_responses: Dict[str, StatusResponse] = {}
 
         for response_type in options.type_descriptions.keys():
-            status_code = http_status_to_string(
-                options.status_catalog.get(response_type, options.default_status_code)
-            )
+            status_code = http_status_to_string(options.status_catalog.get(response_type, options.default_status_code))
 
             # look up response for status code
             if status_code not in status_responses:
@@ -230,17 +279,11 @@ class ResponseBuilder:
 
             # append examples that have the matching response type
             if options.examples:
-                status_response.examples.extend(
-                    example
-                    for example in options.examples
-                    if isinstance(example, response_type)
-                )
+                status_response.examples.extend(example for example in options.examples if isinstance(example, response_type))
 
-        return status_responses
+        return dict(sorted(status_responses.items()))
 
-    def build_response(
-        self, options: ResponseOptions
-    ) -> Dict[str, Union[Response, ResponseRef]]:
+    def build_response(self, options: ResponseOptions) -> Dict[str, Union[Response, ResponseRef]]:
         """
         Groups responses that have the same status code.
         """
@@ -258,10 +301,7 @@ class ResponseBuilder:
             description = " **OR** ".join(
                 filter(
                     None,
-                    (
-                        options.type_descriptions[response_type]
-                        for response_type in response_types
-                    ),
+                    (options.type_descriptions[response_type] for response_type in response_types),
                 )
             )
 
@@ -290,6 +330,27 @@ class ResponseBuilder:
             return Response(description=description)
 
 
+def schema_error_wrapper(schema: SchemaOrRef) -> Schema:
+    "Wraps an error output schema into a top-level error schema."
+
+    return {
+        "type": "object",
+        "properties": {
+            "error": schema,  # type: ignore
+        },
+        "additionalProperties": False,
+        "required": [
+            "error",
+        ],
+    }
+
+
+def sample_error_wrapper(error: JsonType) -> JsonType:
+    "Wraps an error output sample into a top-level error sample."
+
+    return {"error": error}
+
+
 class Generator:
     endpoint: type
     options: Options
@@ -302,6 +363,7 @@ class Generator:
         schema_generator = JsonSchemaGenerator(
             SchemaOptions(
                 definitions_path="#/components/schemas/",
+                use_examples=self.options.use_examples,
                 property_description_fun=options.property_description_fun,
             )
         )
@@ -310,18 +372,14 @@ class Generator:
 
     def _build_type_tag(self, ref: str, schema: Schema) -> Tag:
         definition = f'<SchemaDefinition schemaRef="#/components/schemas/{ref}" />'
-        title = schema.get("title")
-        description = schema.get("description")
+        title = typing.cast(str, schema.get("title"))
+        description = typing.cast(str, schema.get("description"))
         return Tag(
             name=ref,
-            description="\n\n".join(
-                s for s in (title, description, definition) if s is not None
-            ),
+            description="\n\n".join(s for s in (title, description, definition) if s is not None),
         )
 
-    def _build_extra_tag_groups(
-        self, extra_types: Dict[str, List[type]]
-    ) -> Dict[str, List[Tag]]:
+    def _build_extra_tag_groups(self, extra_types: Dict[str, List[type]]) -> Dict[str, List[Tag]]:
         """
         Creates a dictionary of tag group captions as keys, and tag lists as values.
 
@@ -338,15 +396,14 @@ class Generator:
                 schema = self.schema_builder.classdef_to_named_schema(name, extra_type)
                 tag_list.append(self._build_type_tag(name, schema))
 
-            extra_tags[category_name] = tag_list
+            if tag_list:
+                extra_tags[category_name] = tag_list
 
         return extra_tags
 
     def _build_operation(self, op: EndpointOperation) -> Operation:
         doc_string = parse_type(op.func_ref)
-        doc_params = dict(
-            (param.name, param.description) for param in doc_string.params.values()
-        )
+        doc_params = dict((param.name, param.description) for param in doc_string.params.values())
 
         # parameters passed in URL component path
         path_parameters = [
@@ -364,7 +421,7 @@ class Generator:
         query_parameters = []
         for param_name, param_type in op.query_params:
             if is_type_optional(param_type):
-                inner_type = unwrap_optional_type(param_type)
+                inner_type: type = unwrap_optional_type(param_type)
                 required = False
             else:
                 inner_type = param_type
@@ -387,11 +444,7 @@ class Generator:
             builder = ContentBuilder(self.schema_builder)
             request_name, request_type = op.request_param
             requestBody = RequestBody(
-                content={
-                    "application/json": builder.build_media_type(
-                        request_type, op.request_examples
-                    )
-                },
+                content={"application/json": builder.build_media_type(request_type, op.request_examples)},
                 description=doc_params.get(request_name),
                 required=True,
             )
@@ -401,30 +454,22 @@ class Generator:
         # success response types
         if doc_string.returns is None and is_type_union(op.response_type):
             # split union of return types into a list of response types
+            success_type_docstring: Dict[type, Docstring] = {typing.cast(type, item): parse_type(item) for item in unwrap_union_types(op.response_type)}
             success_type_descriptions = {
-                item: parse_type(item).short_description
-                for item in unwrap_union_types(op.response_type)
+                item: doc_string.short_description for item, doc_string in success_type_docstring.items() if doc_string.short_description
             }
         else:
             # use return type as a single response type
-            success_type_descriptions = {
-                op.response_type: (
-                    doc_string.returns.description if doc_string.returns else "OK"
-                )
-            }
+            success_type_descriptions = {op.response_type: (doc_string.returns.description if doc_string.returns else "OK")}
 
         response_examples = op.response_examples or []
-        success_examples = [
-            example
-            for example in response_examples
-            if not isinstance(example, Exception)
-        ]
+        success_examples = [example for example in response_examples if not isinstance(example, Exception)]
 
         content_builder = ContentBuilder(self.schema_builder)
         response_builder = ResponseBuilder(content_builder)
         response_options = ResponseOptions(
             success_type_descriptions,
-            success_examples,
+            success_examples if self.options.use_examples else None,
             self.options.success_responses,
             "200",
         )
@@ -432,27 +477,12 @@ class Generator:
 
         # failure response types
         if doc_string.raises:
-            exception_types: Dict[type, str] = {
-                item.raise_type: item.description for item in doc_string.raises.values()
-            }
-            exception_examples = [
-                example
-                for example in response_examples
-                if isinstance(example, Exception)
-            ]
+            exception_types: Dict[type, str] = {item.raise_type: item.description for item in doc_string.raises.values()}
+            exception_examples = [example for example in response_examples if isinstance(example, Exception)]
 
             if self.options.error_wrapper:
-                schema_transformer = lambda schema: {
-                    "type": "object",
-                    "properties": {
-                        "error": schema,
-                    },
-                    "additionalProperties": False,
-                    "required": [
-                        "error",
-                    ],
-                }
-                sample_transformer = lambda error: {"error": error}
+                schema_transformer = schema_error_wrapper
+                sample_transformer = sample_error_wrapper
             else:
                 schema_transformer = None
                 sample_transformer = None
@@ -465,7 +495,7 @@ class Generator:
             response_builder = ResponseBuilder(content_builder)
             response_options = ResponseOptions(
                 exception_types,
-                exception_examples,
+                exception_examples if self.options.use_examples else None,
                 self.options.error_responses,
                 "500",
             )
@@ -477,9 +507,7 @@ class Generator:
                 f"{op.func_name}_callback": {
                     "{$request.query.callback}": PathItem(
                         post=Operation(
-                            requestBody=RequestBody(
-                                content=builder.build_content(op.event_type)
-                            ),
+                            requestBody=RequestBody(content=builder.build_content(op.event_type)),
                             responses={"200": Response(description="OK")},
                         )
                     )
@@ -503,7 +531,7 @@ class Generator:
     def generate(self) -> Document:
         paths: Dict[str, PathItem] = {}
         endpoint_classes: Set[type] = set()
-        for op in get_endpoint_operations(self.endpoint):
+        for op in get_endpoint_operations(self.endpoint, use_examples=self.options.use_examples):
             endpoint_classes.add(op.defining_class)
 
             operation = self._build_operation(op)
@@ -539,10 +567,7 @@ class Generator:
             )
 
         # types that are produced/consumed by operations
-        type_tags = [
-            self._build_type_tag(ref, schema)
-            for ref, schema in self.schema_builder.schemas.items()
-        ]
+        type_tags = [self._build_type_tag(ref, schema) for ref, schema in self.schema_builder.schemas.items()]
 
         # types that are emitted by events
         event_tags: List[Tag] = []
@@ -555,17 +580,11 @@ class Generator:
         extra_tag_groups: Dict[str, List[Tag]] = {}
         if self.options.extra_types is not None:
             if isinstance(self.options.extra_types, list):
-                extra_tag_groups = self._build_extra_tag_groups(
-                    {"AdditionalTypes": self.options.extra_types}
-                )
+                extra_tag_groups = self._build_extra_tag_groups({"AdditionalTypes": self.options.extra_types})
             elif isinstance(self.options.extra_types, dict):
-                extra_tag_groups = self._build_extra_tag_groups(
-                    self.options.extra_types
-                )
+                extra_tag_groups = self._build_extra_tag_groups(self.options.extra_types)
             else:
-                raise TypeError(
-                    f"type mismatch for collection of extra types: {type(self.options.extra_types)}"
-                )
+                raise TypeError(f"type mismatch for collection of extra types: {type(self.options.extra_types)}")
 
         # list all operations and types
         tags: List[Tag] = []
@@ -611,8 +630,9 @@ class Generator:
             securitySchemes = None
 
         return Document(
-            openapi="3.1.0",
+            openapi=".".join(str(item) for item in self.options.version),
             info=self.options.info,
+            jsonSchemaDialect=("https://json-schema.org/draft/2020-12/schema" if self.options.version >= (3, 1, 0) else None),
             servers=[self.options.server],
             paths=paths,
             components=Components(