feat: docstrings

Author: Anders Brams

openapi_python/generator/model.py

@@ -56,12 +56,14 @@ class FieldDef:
     name: str
     annotation: TypeAnnotation
     required: bool
+    description: str | None = None
 
 
 @dataclass(frozen=True)
 class TypedDictDef:
     name: str
     fields: tuple[FieldDef, ...]
+    description: str | None = None
 
 
 @dataclass(frozen=True)

openapi_python/generator/normalize.py

@@ -363,11 +363,19 @@ def _schema_object_to_type(
                 name=prop_name,
                 annotation=field_type,
                 required=prop_name in required,
+                description=safe_get(prop_schema, "description", type=str),
             )
         )
 
     state = _without_processing(state, name)
-    state = _with_typeddict(state, TypedDictDef(name=name, fields=tuple(fields)))
+    state = _with_typeddict(
+        state,
+        TypedDictDef(
+            name=name,
+            fields=tuple(fields),
+            description=safe_get(schema, "description", type=str),
+        ),
+    )
     return _nullable(NamedAnnotation(name), nullable), state
 
 

openapi_python/generator/render.py

@@ -61,6 +61,17 @@ def _class_field_annotation(field: FieldDef, total_optional: bool) -> str:
     return annotation
 
 
+def _string_literal(value: str) -> str:
+    return repr(value)
+
+
+def _comment(value: str, spaces: int = 0) -> str:
+    prefix = " " * spaces
+    return "\n".join(
+        f"{prefix}# {line}" if line else f"{prefix}#" for line in value.splitlines()
+    )
+
+
 def _supports_typeddict_class_syntax(defn: TypedDictDef) -> bool:
     return all(
         field.name.isidentifier()
@@ -81,6 +92,8 @@ def _supports_typeddict_class_syntax(defn: TypedDictDef) -> bool:
 _JINJA_ENV.filters["annotation"] = _render_annotation
 _JINJA_ENV.filters["field_annotation"] = _field_annotation
 _JINJA_ENV.filters["class_field_annotation"] = _class_field_annotation
+_JINJA_ENV.filters["comment"] = _comment
+_JINJA_ENV.filters["string_literal"] = _string_literal
 
 
 def _render_template(name: str, **context: object) -> str:

openapi_python/generator/templates/typeddict.py.j2

@@ -1,21 +1,36 @@
 {% if class_syntax -%}
 class {{ defn.name }}(TypedDict{% if total_optional %}, total=False{% endif %}):
-{% if not defn.fields %}
+{% if defn.description %}
+    {{ defn.description | string_literal }}
+{% endif %}
+{% if not defn.fields and not defn.description %}
     pass
 {% else %}
 {% for field in defn.fields %}
     {{ field.name }}: {{ field | class_field_annotation(total_optional) }}
+{% if field.description %}
+    {{ field.description | string_literal }}
+{% endif %}
 {% endfor %}
 {% endif %}
 {% elif not defn.fields -%}
 {{ defn.name }} = TypedDict({{ defn.name | repr }}, {})
+{% if defn.description %}
+{{ defn.name }}.__doc__ = {{ defn.description | string_literal }}
+{% endif %}
 {% else -%}
 {{ defn.name }} = TypedDict(
     {{ defn.name | repr }},
     {
 {% for field in defn.fields %}
+{% if field.description %}
+{{ field.description | comment(8) }}
+{% endif %}
         {{ field.name | repr }}: {{ field | field_annotation }},
 {% endfor %}
     },
 )
+{% if defn.description %}
+{{ defn.name }}.__doc__ = {{ defn.description | string_literal }}
+{% endif %}
 {% endif -%}

tests/contract/docstrings/app.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class MyDTO(BaseModel):
+    """This is a descriptive docstring"""
+
+    a: int = Field(description="This is the docstring for a single field")
+
+
+@app.get("/dto", response_model=MyDTO)
+def get_dto() -> MyDTO:
+    return MyDTO(a=1)

tests/contract/docstrings/generate.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import ast
+import importlib
+import json
+from pathlib import Path
+
+from app import app
+
+from openapi_python.generator import GenerationRequest, generate_client
+
+
+def main() -> None:
+    output_dir = Path(__file__).parent / "generated"
+    generate_client(
+        GenerationRequest(
+            output_dir=output_dir,
+            spec_json=json.dumps(app.openapi()),
+            overwrite=True,
+        )
+    )
+
+    source = (output_dir / "my_client" / "types.py").read_text()
+    module = ast.parse(source)
+    dto = next(
+        node
+        for node in module.body
+        if isinstance(node, ast.ClassDef) and node.name == "MyDTO"
+    )
+    generated_types = importlib.import_module("generated.my_client.types")
+
+    assert ast.get_docstring(dto) == "This is a descriptive docstring"
+    assert generated_types.MyDTO.__doc__ == "This is a descriptive docstring"
+    assert "This is the docstring for a single field" in source
+
+
+if __name__ == "__main__":
+    main()

tests/contract/docstrings/usage_async.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import assert_type
+
+from generated.my_client import AsyncClient
+from generated.my_client.types import MyDTO
+
+client = AsyncClient(base_url="http://testserver")
+
+
+async def main() -> None:
+    result = await client.get("/dto")()
+    assert_type(result, MyDTO)
+    assert_type(result["a"], int)

tests/contract/docstrings/usage_sync.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import assert_type
+
+from generated.my_client import Client
+from generated.my_client.types import MyDTO
+
+client = Client(base_url="http://testserver")
+
+result = client.get("/dto")()
+assert_type(result, MyDTO)
+assert_type(result["a"], int)

tests/contract/enum_literal/usage_sync.py

@@ -13,6 +13,8 @@
 
 client = Client(base_url="http://testserver")
 
+res = client.get("/articles/{article_id}")(params={"article_id": 1})
+
 article = client.get("/articles/{article_id}")(params={"article_id": 1})
 assert_type(article, Article)
 assert_type(article["status"], Status)