openapi-python-client 0.23.1__tar.gz → 0.24.0__tar.gz

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openapi-python-client
-Version: 0.23.1
+Version: 0.24.0
 Summary: Generate modern Python clients from OpenAPI
 Project-URL: repository, https://github.com/openapi-generators/openapi-python-client
 Author-email: Dylan Anthony <contact@dylananthony.com>
@@ -131,6 +131,16 @@ class_overrides:
 
 The easiest way to find what needs to be overridden is probably to generate your client and go look at everything in the `models` folder.
 
+### docstrings_on_attributes
+
+By default, when `openapi-python-client` generates a model class, it includes a list of attributes and their
+descriptions in the docstring for the class. If you set this option to `true`, then the attribute descriptions
+will be put in docstrings for the attributes themselves, and will not be in the class docstring.
+
+```yaml
+docstrings_on_attributes: true
+```
+
 ### literal_enums
 
 By default, `openapi-python-client` generates classes inheriting for `Enum` for enums. It can instead use `Literal` 

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/README.md

@@ -97,6 +97,16 @@ class_overrides:
 
 The easiest way to find what needs to be overridden is probably to generate your client and go look at everything in the `models` folder.
 
+### docstrings_on_attributes
+
+By default, when `openapi-python-client` generates a model class, it includes a list of attributes and their
+descriptions in the docstring for the class. If you set this option to `true`, then the attribute descriptions
+will be put in docstrings for the attributes themselves, and will not be in the class docstring.
+
+```yaml
+docstrings_on_attributes: true
+```
+
 ### literal_enums
 
 By default, `openapi-python-client` generates classes inheriting for `Enum` for enums. It can instead use `Literal` 

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/__init__.py

@@ -90,6 +90,7 @@ class Project:
 
         self.env.filters.update(TEMPLATE_FILTERS)
         self.env.globals.update(
+            config=config,
             utils=utils,
             python_identifier=lambda x: utils.PythonIdentifier(x, config.field_prefix),
             class_name=lambda x: utils.ClassName(x, config.field_prefix),

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/config.py

@@ -41,6 +41,7 @@ class ConfigFile(BaseModel):
     package_version_override: Optional[str] = None
     use_path_prefixes_for_title_model_names: bool = True
     post_hooks: Optional[list[str]] = None
+    docstrings_on_attributes: bool = False
     field_prefix: str = "field_"
     generate_all_tags: bool = False
     http_timeout: int = 5
@@ -70,6 +71,7 @@ class Config:
     package_version_override: Optional[str]
     use_path_prefixes_for_title_model_names: bool
     post_hooks: list[str]
+    docstrings_on_attributes: bool
     field_prefix: str
     generate_all_tags: bool
     http_timeout: int
@@ -111,6 +113,7 @@ class Config:
             package_version_override=config_file.package_version_override,
             use_path_prefixes_for_title_model_names=config_file.use_path_prefixes_for_title_model_names,
             post_hooks=post_hooks,
+            docstrings_on_attributes=config_file.docstrings_on_attributes,
             field_prefix=config_file.field_prefix,
             generate_all_tags=config_file.generate_all_tags,
             http_timeout=config_file.http_timeout,

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/parser/bodies.py

@@ -9,6 +9,7 @@ from openapi_python_client.parser.properties import (
     Schemas,
     property_from_data,
 )
+from openapi_python_client.parser.properties.schemas import get_reference_simple_name
 
 from .. import schema as oai
 from ..config import Config
@@ -138,7 +139,7 @@ def _resolve_reference(
     references_seen = []
     while isinstance(body, oai.Reference) and body.ref not in references_seen:
         references_seen.append(body.ref)
-        body = request_bodies.get(body.ref.split("/")[-1])
+        body = request_bodies.get(get_reference_simple_name(body.ref))
     if isinstance(body, oai.Reference):
         return ParseError(detail="Circular $ref in request body", data=body)
     if body is None and references_seen:

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/parser/openapi.py

@@ -51,6 +51,7 @@ class EndpointCollection:
         schemas: Schemas,
         parameters: Parameters,
         request_bodies: dict[str, Union[oai.RequestBody, oai.Reference]],
+        responses: dict[str, Union[oai.Response, oai.Reference]],
         config: Config,
     ) -> tuple[dict[utils.PythonIdentifier, "EndpointCollection"], Schemas, Parameters]:
         """Parse the openapi paths data to get EndpointCollections by tag"""
@@ -78,6 +79,7 @@ class EndpointCollection:
                     schemas=schemas,
                     parameters=parameters,
                     request_bodies=request_bodies,
+                    responses=responses,
                     config=config,
                 )
                 # Add `PathItem` parameters
@@ -151,7 +153,12 @@ class Endpoint:
 
     @staticmethod
     def _add_responses(
-        *, endpoint: "Endpoint", data: oai.Responses, schemas: Schemas, config: Config
+        *,
+        endpoint: "Endpoint",
+        data: oai.Responses,
+        schemas: Schemas,
+        responses: dict[str, Union[oai.Response, oai.Reference]],
+        config: Config,
     ) -> tuple["Endpoint", Schemas]:
         endpoint = deepcopy(endpoint)
         for code, response_data in data.items():
@@ -174,6 +181,7 @@ class Endpoint:
                 status_code=status_code,
                 data=response_data,
                 schemas=schemas,
+                responses=responses,
                 parent_name=endpoint.name,
                 config=config,
             )
@@ -403,6 +411,7 @@ class Endpoint:
         schemas: Schemas,
         parameters: Parameters,
         request_bodies: dict[str, Union[oai.RequestBody, oai.Reference]],
+        responses: dict[str, Union[oai.Response, oai.Reference]],
         config: Config,
     ) -> tuple[Union["Endpoint", ParseError], Schemas, Parameters]:
         """Construct an endpoint from the OpenAPI data"""
@@ -431,7 +440,13 @@ class Endpoint:
         )
         if isinstance(result, ParseError):
             return result, schemas, parameters
-        result, schemas = Endpoint._add_responses(endpoint=result, data=data.responses, schemas=schemas, config=config)
+        result, schemas = Endpoint._add_responses(
+            endpoint=result,
+            data=data.responses,
+            schemas=schemas,
+            responses=responses,
+            config=config,
+        )
         if isinstance(result, ParseError):
             return result, schemas, parameters
         bodies, schemas = body_from_data(
@@ -521,8 +536,14 @@ class GeneratorData:
                 config=config,
             )
         request_bodies = (openapi.components and openapi.components.requestBodies) or {}
+        responses = (openapi.components and openapi.components.responses) or {}
         endpoint_collections_by_tag, schemas, parameters = EndpointCollection.from_data(
-            data=openapi.paths, schemas=schemas, parameters=parameters, request_bodies=request_bodies, config=config
+            data=openapi.paths,
+            schemas=schemas,
+            parameters=parameters,
+            request_bodies=request_bodies,
+            responses=responses,
+            config=config,
         )
 
         enums = (

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/parser/properties/schemas.py

@@ -46,6 +46,13 @@ def parse_reference_path(ref_path_raw: str) -> Union[ReferencePath, ParseError]:
     return cast(ReferencePath, parsed.fragment)
 
 
+def get_reference_simple_name(ref_path: str) -> str:
+    """
+    Takes a path like `/components/schemas/NameOfThing` and returns a string like `NameOfThing`.
+    """
+    return ref_path.split("/")[-1]
+
+
 @define
 class Class:
     """Represents Python class which will be generated from an OpenAPI schema"""
@@ -56,7 +63,7 @@ class Class:
     @staticmethod
     def from_string(*, string: str, config: Config) -> "Class":
         """Get a Class from an arbitrary string"""
-        class_name = string.split("/")[-1]  # Get rid of ref path stuff
+        class_name = get_reference_simple_name(string)  # Get rid of ref path stuff
         class_name = ClassName(class_name, config.field_prefix)
         override = config.class_overrides.get(class_name)
 

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/parser/responses.py

@@ -6,6 +6,7 @@ from typing import Optional, TypedDict, Union
 from attrs import define
 
 from openapi_python_client import utils
+from openapi_python_client.parser.properties.schemas import get_reference_simple_name, parse_reference_path
 
 from .. import Config
 from .. import schema as oai
@@ -79,11 +80,12 @@ def empty_response(
     )
 
 
-def response_from_data(
+def response_from_data(  # noqa: PLR0911
     *,
     status_code: HTTPStatus,
     data: Union[oai.Response, oai.Reference],
     schemas: Schemas,
+    responses: dict[str, Union[oai.Response, oai.Reference]],
     parent_name: str,
     config: Config,
 ) -> tuple[Union[Response, ParseError], Schemas]:
@@ -91,15 +93,17 @@ def response_from_data(
 
     response_name = f"response_{status_code}"
     if isinstance(data, oai.Reference):
-        return (
-            empty_response(
-                status_code=status_code,
-                response_name=response_name,
-                config=config,
-                data=data,
-            ),
-            schemas,
-        )
+        ref_path = parse_reference_path(data.ref)
+        if isinstance(ref_path, ParseError):
+            return ref_path, schemas
+        if not ref_path.startswith("/components/responses/"):
+            return ParseError(data=data, detail=f"$ref to {data.ref} not allowed in responses"), schemas
+        resp_data = responses.get(get_reference_simple_name(ref_path), None)
+        if not resp_data:
+            return ParseError(data=data, detail=f"Could not find reference: {data.ref}"), schemas
+        if not isinstance(resp_data, oai.Response):
+            return ParseError(data=data, detail="Top-level $ref inside components/responses is not supported"), schemas
+        data = resp_data
 
     content = data.content
     if not content:

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/templates/client.py.jinja

@@ -5,6 +5,31 @@ from attrs import define, field, evolve
 import httpx
 
 
+{% set attrs_info = {
+    "raise_on_unexpected_status": namespace(
+        type="bool",
+        default="field(default=False, kw_only=True)",
+        docstring="Whether or not to raise an errors.UnexpectedStatus if the API returns a status code"
+            " that was not documented in the source OpenAPI document. Can also be provided as a keyword"
+            " argument to the constructor."
+    ),
+    "token": namespace(type="str", default="", docstring="The token to use for authentication"),
+    "prefix": namespace(type="str", default='"Bearer"', docstring="The prefix to use for the Authorization header"),
+    "auth_header_name": namespace(type="str", default='"Authorization"', docstring="The name of the Authorization header"),
+} %}
+
+{% macro attr_in_class_docstring(name) %}
+{{ name }}: {{ attrs_info[name].docstring }}
+{%- endmacro %}
+
+{% macro declare_attr(name) %}
+{% set attr = attrs_info[name] %}
+{{ name }}: {{ attr.type }}{% if attr.default %} = {{ attr.default }}{% endif %}
+{% if attr.docstring and config.docstrings_on_attributes +%}
+"""{{ attr.docstring }}"""
+{%- endif %}
+{% endmacro %}
+
 @define
 class Client:
     """A class for keeping track of data related to the API
@@ -29,14 +54,14 @@ class Client:
         ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
 {% endmacro %}
 {{ httpx_args_docstring() }}
+{% if not config.docstrings_on_attributes %}
 
     Attributes:
-        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
-            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
-            argument to the constructor.
+        {{ attr_in_class_docstring("raise_on_unexpected_status") | wordwrap(101) | indent(12) }}
+{% endif %}
     """
 {% macro attributes() %}
-    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
+    {{ declare_attr("raise_on_unexpected_status") | indent(4) }}
     _base_url: str = field(alias="base_url")
     _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
     _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
@@ -147,20 +172,20 @@ class AuthenticatedClient:
     """A Client which has been authenticated for use on secured endpoints
 
 {{ httpx_args_docstring() }}
+{% if not config.docstrings_on_attributes %}
 
     Attributes:
-        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
-            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
-            argument to the constructor.
-        token: The token to use for authentication
-        prefix: The prefix to use for the Authorization header
-        auth_header_name: The name of the Authorization header
+        {{ attr_in_class_docstring("raise_on_unexpected_status") | wordwrap(101) | indent(12) }}
+        {{ attr_in_class_docstring("token") | indent(8) }}
+        {{ attr_in_class_docstring("prefix") | indent(8) }}
+        {{ attr_in_class_docstring("auth_header_name") | indent(8) }}
+{% endif %}
     """
 
 {{ attributes() }}
-    token: str
-    prefix: str = "Bearer"
-    auth_header_name: str = "Authorization"
+    {{ declare_attr("token") | indent(4) }}
+    {{ declare_attr("prefix") | indent(4) }}
+    {{ declare_attr("auth_header_name") | indent(4) }}
 
 {{ builders("AuthenticatedClient") }}
 {{ httpx_stuff("AuthenticatedClient", "self._headers[self.auth_header_name] = f\"{self.prefix} {self.token}\" if self.prefix else self.token") }}

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/templates/helpers.jinja

@@ -1,8 +1,10 @@
-{% macro safe_docstring(content) %}
+{% macro safe_docstring(content, omit_if_empty=False) %}
 {# This macro returns the provided content as a docstring, set to a raw string if it contains a backslash #}
+{% if (not omit_if_empty) or (content | trim) %}
 {% if '\\' in content -%}
 r""" {{ content }} """
 {%- else -%}
 """ {{ content }} """
 {%- endif -%}
+{% endif %}
 {% endmacro %}

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/openapi_python_client/templates/model.py.jinja

@@ -47,25 +47,34 @@ T = TypeVar("T", bound="{{ class_name }}")
         {{ model.example | string | wordwrap(112) | indent(12) }}
 
     {% endif %}
-    {% if model.required_properties or model.optional_properties %}
+    {% if (not config.docstrings_on_attributes) and (model.required_properties or model.optional_properties) %}
     Attributes:
     {% for property in model.required_properties + model.optional_properties %}
         {{ property.to_docstring() | wordwrap(112) | indent(12) }}
     {% endfor %}{% endif %}
 {% endmacro %}
 
+{% macro declare_property(property) %}
+{%- if config.docstrings_on_attributes and property.description -%}
+{{ property.to_string() }}
+{{ safe_docstring(property.description, omit_if_empty=True) | wordwrap(112) }}
+{%- else -%}
+{{ property.to_string() }}
+{%- endif -%}
+{% endmacro %}
+
 @_attrs_define
 class {{ class_name }}:
-    {{ safe_docstring(class_docstring_content(model)) | indent(4) }}
+    {{ safe_docstring(class_docstring_content(model), omit_if_empty=config.docstrings_on_attributes) | indent(4) }}
 
     {% for property in model.required_properties + model.optional_properties %}
     {% if property.default is none and property.required %}
-    {{ property.to_string() }}
+    {{ declare_property(property) | indent(4) }}
     {% endif %}
     {% endfor %}
     {% for property in model.required_properties + model.optional_properties %}
     {% if property.default is not none or not property.required %}
-    {{ property.to_string() }}
+    {{ declare_property(property) | indent(4) }}
     {% endif %}
     {% endfor %}
     {% if model.additional_properties %}

{openapi_python_client-0.23.1 → openapi_python_client-0.24.0}/pyproject.toml

@@ -18,7 +18,7 @@ dependencies = [
     "typing-extensions>=4.8.0,<5.0.0",
 ]
 name = "openapi-python-client"
-version = "0.23.1"
+version = "0.24.0"
 description = "Generate modern Python clients from OpenAPI"
 keywords = [
     "OpenAPI",