python-openapi 0.2.0__tar.gz → 0.3.0__tar.gz

{python_openapi-0.2.0 → python_openapi-0.3.0}/LICENSE

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

{python_openapi-0.2.0/python_openapi.egg-info → python_openapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-openapi
-Version: 0.2.0
+Version: 0.3.0
 Summary: Generate an OpenAPI specification from a Python class definition
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
@@ -12,20 +12,29 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-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: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp>=3.12
-Requires-Dist: json_strong_typing>=0.3.9
+Requires-Dist: json_strong_typing>=0.4
+Provides-Extra: proxy
+Requires-Dist: aiohttp>=3.13; extra == "proxy"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: PyYAML; extra == "dev"
+Requires-Dist: Pygments; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-Pygments; extra == "dev"
 Dynamic: license-file
 
 # Generate an OpenAPI specification from a Python class
@@ -37,7 +46,7 @@ Dynamic: license-file
 * supports standard and asynchronous functions (`async def`)
 * maps function name prefixes such as `get_` or `create_` to HTTP GET, POST, PUT, DELETE, PATCH
 * handles both simple and composite types (`int`, `str`, `Enum`, `@dataclass`)
-* handles generic types (`list[T]`, `dict[K, V]`, `Optional[T]`, `Union[T1, T2, T3]`)
+* handles generic types (`list[T]`, `dict[K, V]`, `T | None`, `T1 | T2 | T3`)
 * maps Python positional-only and keyword-only arguments (of simple types) to path and query parameters, respectively
 * maps composite types to HTTP request body
 * supports user-defined routes, request and response samples with decorator `@webmethod`
@@ -162,7 +171,7 @@ OpenAPI supports specifying [examples](https://spec.openapis.org/oas/latest.html
             Teacher("Vacska", "Mati", "Négyszögletű Kerek Erdő"),
         ],
     )
-    def get_member_by_name(self, family: str, given: str, /) -> Union[Student, Teacher]:
+    def get_member_by_name(self, family: str, given: str, /) -> Student | Teacher:
         ...
 ```
 

{python_openapi-0.2.0 → python_openapi-0.3.0}/README.md

@@ -7,7 +7,7 @@
 * supports standard and asynchronous functions (`async def`)
 * maps function name prefixes such as `get_` or `create_` to HTTP GET, POST, PUT, DELETE, PATCH
 * handles both simple and composite types (`int`, `str`, `Enum`, `@dataclass`)
-* handles generic types (`list[T]`, `dict[K, V]`, `Optional[T]`, `Union[T1, T2, T3]`)
+* handles generic types (`list[T]`, `dict[K, V]`, `T | None`, `T1 | T2 | T3`)
 * maps Python positional-only and keyword-only arguments (of simple types) to path and query parameters, respectively
 * maps composite types to HTTP request body
 * supports user-defined routes, request and response samples with decorator `@webmethod`
@@ -132,7 +132,7 @@ OpenAPI supports specifying [examples](https://spec.openapis.org/oas/latest.html
             Teacher("Vacska", "Mati", "Négyszögletű Kerek Erdő"),
         ],
     )
-    def get_member_by_name(self, family: str, given: str, /) -> Union[Student, Teacher]:
+    def get_member_by_name(self, family: str, given: str, /) -> Student | Teacher:
         ...
 ```
 

{python_openapi-0.2.0 → python_openapi-0.3.0}/pyopenapi/__init__.py

@@ -1,14 +1,14 @@
 """
 Generate an OpenAPI specification from a Python class definition
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2021-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/pyopenapi
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2022-2025, Levente Hunyadi"
+__copyright__ = "Copyright 2021-2026, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"

{python_openapi-0.2.0 → python_openapi-0.3.0}/pyopenapi/decorators.py

@@ -1,12 +1,12 @@
 """
 Generate an OpenAPI specification from a Python class definition
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2021-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/pyopenapi
 """
 
-from typing import Any, Callable, Optional, TypeVar
+from typing import Any, Callable, TypeVar
 
 from .metadata import WebMethod
 from .options import *  # noqa: F403
@@ -16,12 +16,13 @@ F = TypeVar("F", bound=Callable[..., Any])
 
 
 def webmethod(
-    route: Optional[str] = None,
-    public: Optional[bool] = False,
-    request_example: Optional[Any] = None,
-    response_example: Optional[Any] = None,
-    request_examples: Optional[list[Any]] = None,
-    response_examples: Optional[list[Any]] = None,
+    route: str | None = None,
+    public: bool = False,
+    deprecated: bool = False,
+    request_example: Any | None = None,
+    response_example: Any | None = None,
+    request_examples: list[Any] | None = None,
+    response_examples: list[Any] | None = None,
 ) -> Callable[[F], F]:
     """
     Decorator that supplies additional metadata to an endpoint operation function.
@@ -45,7 +46,13 @@ def webmethod(
         response_examples = [response_example]
 
     def wrap(cls: F) -> F:
-        cls.__webmethod__ = WebMethod(route=route, public=public or False, request_examples=request_examples, response_examples=response_examples)  # type: ignore[attr-defined]
+        cls.__webmethod__ = WebMethod(  # type: ignore[attr-defined]
+            route=route,
+            public=public or False,
+            deprecated=deprecated or False,
+            request_examples=request_examples,
+            response_examples=response_examples,
+        )
         return cls
 
     return wrap

{python_openapi-0.2.0 → python_openapi-0.3.0}/pyopenapi/generator.py

@@ -1,7 +1,7 @@
 """
 Generate an OpenAPI specification from a Python class definition
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2021-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/pyopenapi
 """
@@ -9,14 +9,16 @@ Copyright 2022-2025, Levente Hunyadi
 import dataclasses
 import hashlib
 import ipaddress
+import operator
 import typing
 from dataclasses import dataclass
+from functools import reduce
 from http import HTTPStatus
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable
 
 from strong_typing.core import JsonType, Schema
 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.inspection import is_type_optional, is_type_union, unwrap_optional_type, unwrap_union_types
 from strong_typing.name import python_type_to_name
 from strong_typing.schema import JsonSchemaGenerator, SchemaOptions, get_schema_identifier, register_schema
 from strong_typing.serialization import json_dump_string, object_to_json
@@ -36,7 +38,6 @@ from .specification import (
     RequestBody,
     Response,
     ResponseRef,
-    SchemaOrRef,
     SchemaRef,
     Tag,
     TagGroup,
@@ -74,14 +75,13 @@ register_schema(
 def http_status_to_string(status_code: HTTPStatusCode) -> str:
     "Converts an HTTP status code to a string."
 
-    if isinstance(status_code, HTTPStatus):
-        return str(status_code.value)
-    elif isinstance(status_code, int):
-        return str(status_code)
-    elif isinstance(status_code, str):
-        return status_code
-    else:
-        raise TypeError("expected: HTTP status code")
+    match status_code:
+        case HTTPStatus():
+            return str(status_code.value)
+        case int():
+            return str(status_code)
+        case str():
+            return status_code
 
 
 class SchemaBuilder:
@@ -92,7 +92,7 @@ class SchemaBuilder:
         self.schema_generator = schema_generator
         self.schemas = {}
 
-    def classdef_to_schema(self, typ: type) -> Schema:
+    def classdef_to_schema(self, typ: type[Any]) -> Schema:
         """
         Converts a type to a JSON schema.
         For nested types found in the type hierarchy, adds the type to the schema registry in the OpenAPI specification section `components`.
@@ -106,12 +106,12 @@ class SchemaBuilder:
 
         return type_schema
 
-    def classdef_to_named_schema(self, name: str, typ: type) -> Schema:
+    def classdef_to_named_schema(self, name: str, typ: type[Any]) -> Schema:
         schema = self.classdef_to_schema(typ)
         self._add_ref(name, schema)
         return schema
 
-    def classdef_to_ref(self, typ: type) -> SchemaOrRef:
+    def classdef_to_ref(self, typ: type[Any]) -> Schema | SchemaRef:
         """
         Converts a type to a JSON schema, and if possible, returns a schema reference.
         For composite types (such as classes), adds the type to the schema registry in the OpenAPI specification section `components`.
@@ -145,35 +145,35 @@ class SchemaBuilder:
 
 class ContentBuilder:
     schema_builder: SchemaBuilder
-    schema_transformer: Optional[Callable[[SchemaOrRef], SchemaOrRef]]
-    sample_transformer: Optional[Callable[[JsonType], JsonType]]
+    schema_transformer: Callable[[Schema | SchemaRef], Schema | SchemaRef] | None
+    sample_transformer: Callable[[JsonType], JsonType] | None
 
     def __init__(
         self,
         schema_builder: SchemaBuilder,
-        schema_transformer: Optional[Callable[[SchemaOrRef], SchemaOrRef]] = None,
-        sample_transformer: Optional[Callable[[JsonType], JsonType]] = None,
+        schema_transformer: Callable[[Schema | SchemaRef], Schema | SchemaRef] | None = None,
+        sample_transformer: Callable[[JsonType], JsonType] | None = None,
     ) -> None:
         self.schema_builder = schema_builder
         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[Any], examples: list[Any] | None = None) -> dict[str, MediaType]:
         "Creates the content subtree for a request or response."
 
-        if is_generic_list(payload_type):
+        if typing.get_origin(payload_type) is list:
             media_type = "application/jsonl"
-            item_type = unwrap_generic_list(payload_type)
+            (item_type,) = typing.get_args(payload_type)  # unpack single tuple element
         else:
             media_type = "application/json"
             item_type = payload_type
 
         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[Any], examples: list[Any] | None = None) -> MediaType:
         schema = self.schema_builder.classdef_to_ref(item_type)
         if self.schema_transformer:
-            schema_transformer: Callable[[SchemaOrRef], SchemaOrRef] = self.schema_transformer
+            schema_transformer: Callable[[Schema | SchemaRef], Schema | SchemaRef] = self.schema_transformer
             schema = schema_transformer(schema)
 
         if not examples:
@@ -187,12 +187,12 @@ class ContentBuilder:
             examples=self._build_examples(examples),
         )
 
-    def _build_examples(self, examples: list[Any]) -> dict[str, Union[Example, ExampleRef]]:
+    def _build_examples(self, examples: list[Any]) -> dict[str, Example | ExampleRef]:
         "Creates a set of several examples for a media type."
 
         builder = ExampleBuilder(self.sample_transformer)
 
-        results: dict[str, Union[Example, ExampleRef]] = {}
+        results: dict[str, Example | ExampleRef] = {}
         for example in examples:
             name, value = builder.get_named(example)
             results[name] = Example(value=value)
@@ -211,7 +211,7 @@ class ExampleBuilder:
 
     def __init__(
         self,
-        sample_transformer: Optional[Callable[[JsonType], JsonType]] = None,
+        sample_transformer: Callable[[JsonType], JsonType] | None = None,
     ) -> None:
         if sample_transformer:
             self.sample_transformer = sample_transformer
@@ -227,7 +227,7 @@ class ExampleBuilder:
     def get_named(self, example: Any) -> tuple[str, JsonType]:
         value = self._get_value(example)
 
-        name: Optional[str] = None
+        name: str | None = None
 
         if type(example).__str__ is not object.__str__:  # type: ignore[comparison-overlap]
             friendly_name = str(example)
@@ -252,8 +252,8 @@ class ResponseOptions:
     :param default_status_code: HTTP status code assigned to responses that have no mapping.
     """
 
-    type_descriptions: dict[type, str]
-    examples: Optional[list[Any]]
+    type_descriptions: dict[type[Any], str]
+    examples: list[Any] | None
     status_catalog: dict[type, HTTPStatusCode]
     default_status_code: HTTPStatusCode
 
@@ -261,8 +261,8 @@ class ResponseOptions:
 @dataclass
 class StatusResponse:
     status_code: str
-    types: list[type] = dataclasses.field(default_factory=list)
-    examples: list[Any] = dataclasses.field(default_factory=list)
+    types: list[type[Any]] = dataclasses.field(default_factory=list[type[Any]])
+    examples: list[Any] = dataclasses.field(default_factory=list[Any])
 
 
 class ResponseBuilder:
@@ -291,20 +291,20 @@ class ResponseBuilder:
 
         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, Response | ResponseRef]:
         """
         Groups responses that have the same status code.
         """
 
-        responses: dict[str, Union[Response, ResponseRef]] = {}
+        responses: dict[str, Response | ResponseRef] = {}
         status_responses = self._get_status_responses(options)
         for status_code, status_response in status_responses.items():
             response_types = tuple(status_response.types)
-            if len(response_types) > 1:
-                composite_response_type: type = Union[response_types]  # type: ignore
+            composite_response_type: type[Any] | None
+            if len(response_types) > 0:
+                composite_response_type = reduce(operator.or_, response_types)
             else:
-                (response_type,) = response_types
-                composite_response_type = response_type
+                composite_response_type = None
 
             description = " **OR** ".join(
                 filter(
@@ -323,9 +323,9 @@ class ResponseBuilder:
 
     def _build_response(
         self,
-        response_type: Optional[type],
+        response_type: type[Any] | None,
         description: str,
-        examples: Optional[list[Any]] = None,
+        examples: list[Any] | None = None,
     ) -> Response:
         "Creates a response subtree."
 
@@ -338,7 +338,7 @@ class ResponseBuilder:
             return Response(description=description)
 
 
-def schema_error_wrapper(schema: SchemaOrRef) -> Schema:
+def schema_error_wrapper(schema: Schema | SchemaRef) -> Schema:
     "Wraps an error output schema into a top-level error schema."
 
     return {
@@ -360,12 +360,12 @@ def sample_error_wrapper(error: JsonType) -> JsonType:
 
 
 class Generator:
-    endpoint: type
+    endpoint: type[Any]
     options: Options
     schema_builder: SchemaBuilder
     responses: dict[str, Response]
 
-    def __init__(self, endpoint: type, options: Options) -> None:
+    def __init__(self, endpoint: type[Any], options: Options) -> None:
         self.endpoint = endpoint
         self.options = options
         schema_generator = JsonSchemaGenerator(
@@ -380,14 +380,14 @@ class Generator:
 
     def _build_type_tag(self, ref: str, schema: Schema) -> Tag:
         definition = f'<SchemaDefinition schemaRef="#/components/schemas/{ref}" />'
-        title = typing.cast(str, schema.get("title"))
-        description = typing.cast(str, schema.get("description"))
+        title = typing.cast(str | None, schema.get("title"))
+        description = typing.cast(str | None, schema.get("description"))
         return Tag(
             name=ref,
             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[Any]]]) -> dict[str, list[Tag]]:
         """
         Creates a dictionary of tag group captions as keys, and tag lists as values.
 
@@ -426,10 +426,10 @@ class Generator:
         ]
 
         # parameters passed in URL component query string
-        query_parameters = []
+        query_parameters: list[Parameter] = []
         for param_name, param_type in op.query_params:
             if is_type_optional(param_type):
-                inner_type: type = unwrap_optional_type(param_type)
+                inner_type: type[Any] = unwrap_optional_type(param_type)
                 required = False
             else:
                 inner_type = param_type
@@ -462,7 +462,9 @@ 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_docstring: dict[type[Any], Docstring] = {
+                typing.cast(type[Any], item): parse_type(item) for item in unwrap_union_types(op.response_type)
+            }
             success_type_descriptions = {
                 item: doc_string.short_description for item, doc_string in success_type_docstring.items() if doc_string.short_description
             }
@@ -533,12 +535,13 @@ class Generator:
             requestBody=requestBody,
             responses=responses,
             callbacks=callbacks,
+            deprecated=op.deprecated,
             security=[] if op.public else None,
         )
 
     def generate(self) -> Document:
         paths: dict[str, PathItem] = {}
-        endpoint_classes: set[type] = set()
+        endpoint_classes: set[type[Any]] = set()
         for op in get_endpoint_operations(self.endpoint, use_examples=self.options.use_examples):
             endpoint_classes.add(op.defining_class)
 
@@ -565,7 +568,7 @@ class Generator:
 
         operation_tags: list[Tag] = []
         for cls in endpoint_classes:
-            doc_string = parse_type(cls)
+            doc_string = parse_type(cls)  # type: ignore[arg-type]
             operation_tags.append(
                 Tag(
                     name=cls.__name__,
@@ -587,12 +590,11 @@ class Generator:
         # types that are explicitly declared
         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})
-            elif isinstance(self.options.extra_types, dict):
-                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)}")
+            match self.options.extra_types:
+                case list():
+                    extra_tag_groups = self._build_extra_tag_groups({"AdditionalTypes": self.options.extra_types})
+                case dict():
+                    extra_tag_groups = self._build_extra_tag_groups(self.options.extra_types)
 
         # list all operations and types
         tags: list[Tag] = []
@@ -602,7 +604,7 @@ class Generator:
         for extra_tag_group in extra_tag_groups.values():
             tags.extend(extra_tag_group)
 
-        tag_groups = []
+        tag_groups: list[TagGroup] = []
         if operation_tags:
             tag_groups.append(
                 TagGroup(

{python_openapi-0.2.0 → python_openapi-0.3.0}/pyopenapi/metadata.py

@@ -1,13 +1,13 @@
 """
 Generate an OpenAPI specification from a Python class definition
 
-Copyright 2022-2025, Levente Hunyadi
+Copyright 2021-2026, Levente Hunyadi
 
 :see: https://github.com/hunyadi/pyopenapi
 """
 
 from dataclasses import dataclass
-from typing import Any, Optional
+from typing import Any
 
 
 @dataclass
@@ -17,11 +17,13 @@ class WebMethod:
 
     :param route: The URL path pattern associated with this operation which path parameters are substituted into.
     :param public: True if the operation can be invoked without prior authentication.
+    :param deprecated: True if consumers should refrain from using the operation.
     :param request_examples: Sample requests that the operation might take. Pass a list of objects, not JSON.
     :param response_examples: Sample responses that the operation might produce. Pass a list of objects, not JSON.
     """
 
-    route: Optional[str] = None
+    route: str | None = None
     public: bool = False
-    request_examples: Optional[list[Any]] = None
-    response_examples: Optional[list[Any]] = None
+    deprecated: bool = False
+    request_examples: list[Any] | None = None
+    response_examples: list[Any] | None = None