flask-ast-openapi 0.2.0__tar.gz → 0.2.1__tar.gz

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-ast-openapi
-Version: 0.2.0
+Version: 0.2.1
 Summary: Generate OpenAPI specifications from Flask source code using AST
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -55,6 +55,8 @@ It also provides optional Swagger UI integration for Flask applications.
 * Marshmallow request schema support
 * Marshmallow response schema support
 * Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -431,6 +433,23 @@ def create_user():
     ...
 ```
 
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
+
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
 ## Response Schemas
@@ -785,12 +804,12 @@ Future development may include:
 Current version:
 
 ```text
-0.2.0
+0.2.1
 ```
 
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

flask_ast_openapi-0.2.0/src/flask_ast_openapi.egg-info/PKG-INFO → flask_ast_openapi-0.2.1/README.md

@@ -1,15 +1,3 @@
-Metadata-Version: 2.4
-Name: flask-ast-openapi
-Version: 0.2.0
-Summary: Generate OpenAPI specifications from Flask source code using AST
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: Flask>=3.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Dynamic: license-file
-
 # flask-ast-openapi
 
 Generate OpenAPI 3 specifications from Flask source code using Python's Abstract Syntax Tree (AST).
@@ -31,10 +19,10 @@ It also provides optional Swagger UI integration for Flask applications.
   * `@app.put(...)`
   * `@app.patch(...)`
   * `@app.delete(...)`
-* Blueprint route support
-* Blueprint `url_prefix` support
-* Nested and cross-file Blueprint registration support
-* Automatic Blueprint tags for Swagger UI grouping
+* Blueprint route support
+* Blueprint `url_prefix` support
+* Nested and cross-file Blueprint registration support
+* Automatic Blueprint tags for Swagger UI grouping
 * Flask path parameter conversion to OpenAPI format
 * Flask converter support:
 
@@ -53,8 +41,10 @@ It also provides optional Swagger UI integration for Flask applications.
 * Function docstrings as OpenAPI descriptions
 * Synchronous and asynchronous Flask route support
 * Marshmallow request schema support
-* Marshmallow response schema support
-* Cross-file Marshmallow schema resolution
+* Marshmallow response schema support
+* Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -417,7 +407,7 @@ class UserRequestSchema(Schema):
     active = fields.Boolean()
 ```
 
-A route can reference the schema from its docstring:
+A route can reference the schema from its docstring:
 
 ```python
 @app.post("/users")
@@ -428,8 +418,25 @@ def create_user():
     :request: UserRequestSchema
     """
 
-    ...
-```
+    ...
+```
+
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
 
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
@@ -782,15 +789,15 @@ Future development may include:
 
 ## Version
 
-Current version:
-
-```text
-0.2.0
-```
-
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Current version:
+
+```text
+0.2.1
+```
+
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flask-ast-openapi"
-version = "0.2.0"
+version = "0.2.1"
 description = "Generate OpenAPI specifications from Flask source code using AST"
 readme = "README.md"
 requires-python = ">=3.10"

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.1}/src/flask_ast_openapi/generator.py

@@ -32,8 +32,10 @@ class RouteDefinition:
     auth_schemes: list[str] = field(default_factory=list)
     auth_scheme_mode: str = "and"
     description: str | None = None
-    request_schema: dict[str, Any] | None = None
+    request_schema: dict[str, Any] | None = None
     response_schema: dict[str, Any] | None = None
+    request_content_type: str | None = "application/json"
+    response_content_type: str = "application/json"
     tag: str | None = None
 @dataclass
 class PathParameter:
@@ -283,10 +285,16 @@ class FlaskASTOpenAPI:
                                 function
                             )
                         ),
-                        request_schema=self.build_request_schema_from_docstring(
-                            tree,
-                            function,
-                        ),
+                        request_schema=self.build_request_schema_from_docstring(
+                            tree,
+                            function,
+                        ),
+                        request_content_type=(
+                            self.extract_request_content_type(function)
+                        ),
+                        response_content_type=(
+                            self.extract_response_content_type(function)
+                        ),
                         uses_json_body=(
                             self.function_uses_json_body(
                                 function
@@ -451,16 +459,20 @@ class FlaskASTOpenAPI:
         operation: dict[str, Any] = {
             "operationId": route.function_name,
             "parameters": parameters,
-            "responses": self.build_openapi_responses(
-                response_status_codes,
-                response_schemas,
-            ),
+            "responses": self.build_openapi_responses(
+                response_status_codes,
+                response_schemas,
+                route.response_content_type,
+            ),
         }
 
         if route.tag:
             operation["tags"] = [route.tag]
 
-        if route.uses_json_body or route.request_schema is not None:
+        if (
+            route.request_content_type is not None
+            and (route.uses_json_body or route.request_schema is not None)
+        ):
             request_schema = route.request_schema
 
             if request_schema is None:
@@ -471,12 +483,12 @@ class FlaskASTOpenAPI:
                 )
 
             operation["requestBody"] = {
-                "required": True,
-                "content": {
-                    "application/json": {
-                        "schema": request_schema,
-                    }
-                },
+                "required": True,
+                "content": {
+                    route.request_content_type: {
+                        "schema": request_schema,
+                    }
+                },
         }
 
         if route.description:
@@ -795,7 +807,7 @@ class FlaskASTOpenAPI:
             }
             for name in names
         ]
-    def function_uses_json_body(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> bool:
+    def function_uses_json_body(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> bool:
         """Check whether a route function reads a JSON request body."""
 
         for node in ast.walk(function):
@@ -816,7 +828,79 @@ class FlaskASTOpenAPI:
                 ):
                     return True
 
-        return False 
+        return False 
+
+    def function_uses_multipart_body(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> bool:
+        """Check whether a route reads form fields or uploaded files."""
+
+        for node in ast.walk(function):
+            if not isinstance(node, ast.Attribute):
+                continue
+
+            if (
+                isinstance(node.value, ast.Name)
+                and node.value.id == "request"
+                and node.attr in {"form", "files"}
+            ):
+                return True
+
+        return False
+
+    def extract_docstring_directive(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+        directive: str,
+    ) -> str | None:
+        """Extract a named ``:directive: value`` from a docstring."""
+
+        docstring = ast.get_docstring(function)
+        if not docstring:
+            return None
+
+        match = re.search(
+            rf"^\s*:{re.escape(directive)}:\s*([^\s]+)",
+            docstring,
+            re.MULTILINE,
+        )
+        return match.group(1) if match else None
+
+    def extract_request_content_type(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> str | None:
+        """Infer request body media type, allowing a docstring override."""
+
+        explicit = self.extract_docstring_directive(
+            function,
+            "request-content-type",
+        )
+        if explicit:
+            return explicit
+
+        if self.function_uses_multipart_body(function):
+            return "multipart/form-data"
+
+        if self.function_uses_json_body(function):
+            return "application/json"
+
+        return None
+
+    def extract_response_content_type(
+        self,
+        function: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> str:
+        """Return the declared response media type or JSON by default."""
+
+        return (
+            self.extract_docstring_directive(
+                function,
+                "response-content-type",
+            )
+            or "application/json"
+        )
     def extract_json_body_field_names(self,function: ast.FunctionDef | ast.AsyncFunctionDef,) -> list[str]:
         """Extract JSON body field names used inside a route function."""
 
@@ -1151,10 +1235,11 @@ class FlaskASTOpenAPI:
                 status_codes.append(status_code)
 
         return status_codes
-    def build_openapi_responses(
-    self,
-    status_codes: list[int],
-    response_schemas: dict[int, dict[str, Any]] | None = None,
+    def build_openapi_responses(
+        self,
+        status_codes: list[int],
+        response_schemas: dict[int, dict[str, Any]] | None = None,
+        content_type: str = "application/json",
 ) -> dict[str, Any]:
         """Build OpenAPI responses from status codes and schemas."""
 
@@ -1176,11 +1261,11 @@ class FlaskASTOpenAPI:
             schema = response_schemas.get(status_code)
 
             if schema:
-                response["content"] = {
-                    "application/json": {
-                        "schema": schema,
-                    }
-                }
+                response["content"] = {
+                    content_type: {
+                        "schema": schema,
+                    }
+                }
 
             responses[str(status_code)] = response
 

flask_ast_openapi-0.2.0/README.md → flask_ast_openapi-0.2.1/src/flask_ast_openapi.egg-info/PKG-INFO

@@ -1,3 +1,15 @@
+Metadata-Version: 2.4
+Name: flask-ast-openapi
+Version: 0.2.1
+Summary: Generate OpenAPI specifications from Flask source code using AST
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
 # flask-ast-openapi
 
 Generate OpenAPI 3 specifications from Flask source code using Python's Abstract Syntax Tree (AST).
@@ -19,10 +31,10 @@ It also provides optional Swagger UI integration for Flask applications.
   * `@app.put(...)`
   * `@app.patch(...)`
   * `@app.delete(...)`
-* Blueprint route support
-* Blueprint `url_prefix` support
-* Nested and cross-file Blueprint registration support
-* Automatic Blueprint tags for Swagger UI grouping
+* Blueprint route support
+* Blueprint `url_prefix` support
+* Nested and cross-file Blueprint registration support
+* Automatic Blueprint tags for Swagger UI grouping
 * Flask path parameter conversion to OpenAPI format
 * Flask converter support:
 
@@ -41,8 +53,10 @@ It also provides optional Swagger UI integration for Flask applications.
 * Function docstrings as OpenAPI descriptions
 * Synchronous and asynchronous Flask route support
 * Marshmallow request schema support
-* Marshmallow response schema support
-* Cross-file Marshmallow schema resolution
+* Marshmallow response schema support
+* Cross-file Marshmallow schema resolution
+* Automatic request content-type detection for JSON and multipart forms
+* Request and response content-type docstring overrides
 * Nested Marshmallow schema support
 * OpenAPI component schema generation
 * Configurable authentication decorators
@@ -419,6 +433,23 @@ def create_user():
     ...
 ```
 
+JSON bodies are detected from `request.get_json()` and `request.json`.
+Multipart bodies are detected from `request.form` and `request.files`.
+For custom media types, use docstring directives:
+
+```python
+@app.post("/documents")
+def upload_document():
+    """
+    :request: DocumentUploadSchema
+    :response: DocumentResponseSchema
+    :request-content-type: multipart/form-data
+    :response-content-type: application/json
+    """
+
+    ...
+```
+
 The generator detects `UserRequestSchema` and creates an OpenAPI request-body schema.
 
 ## Response Schemas
@@ -770,15 +801,15 @@ Future development may include:
 
 ## Version
 
-Current version:
-
-```text
-0.2.0
-```
-
-Version `0.2.0` adds nested cross-file Blueprint prefix resolution,
-automatic Blueprint tags, cross-file Marshmallow schema resolution, and
-default exclusion of test and virtual-environment directories.
+Current version:
+
+```text
+0.2.1
+```
+
+Version `0.2.1` adds automatic JSON and multipart request content-type
+detection, explicit request/response media-type overrides, and avoids creating
+request bodies for header-only and path-only inputs.
 
 ## License
 

{flask_ast_openapi-0.2.0 → flask_ast_openapi-0.2.1}/tests/test_generator.py

@@ -6405,3 +6405,89 @@ def create_user():
     response_schema = operation["responses"]["200"]["content"]["application/json"]["schema"]
     assert request_schema["properties"]["name"] == {"type": "string"}
     assert response_schema["properties"]["id"] == {"type": "integer"}
+
+
+def test_generate_infers_multipart_form_data(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class UploadSchema(Schema):
+    title = fields.String(required=True)
+    file = fields.Raw(required=True)
+
+upload_bp = Blueprint("upload", __name__)
+
+@upload_bp.route("/upload", methods=["POST"])
+def upload():
+    \"\"\":request: UploadSchema\"\"\"
+    title = request.form.get("title")
+    file = request.files.get("file")
+    return {}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+    content = spec["paths"]["/upload"]["post"]["requestBody"]["content"]
+
+    assert "multipart/form-data" in content
+    assert "application/json" not in content
+
+
+def test_generate_does_not_create_body_for_header_only_schema(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class TokenSchema(Schema):
+    token = fields.String(required=True)
+
+auth_bp = Blueprint("auth", __name__)
+
+@auth_bp.route("/validate", methods=["POST"])
+def validate():
+    \"\"\":request: TokenSchema\"\"\"
+    token = request.headers.get("Authorization")
+    return {}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+
+    assert "requestBody" not in spec["paths"]["/validate"]["post"]
+
+
+def test_docstring_can_override_request_and_response_content_types(tmp_path):
+    (tmp_path / "routes.py").write_text(
+        """
+from flask import Blueprint, request
+from marshmallow import Schema, fields
+
+class PayloadSchema(Schema):
+    value = fields.String(required=True)
+
+bp = Blueprint("custom", __name__)
+
+@bp.route("/custom", methods=["POST"])
+def custom():
+    \"\"\"
+    :request: PayloadSchema
+    :response: PayloadSchema
+    :request-content-type: application/x-www-form-urlencoded
+    :response-content-type: application/problem+json
+    \"\"\"
+    value = request.form.get("value")
+    return {"value": value}, 200
+""",
+        encoding="utf-8",
+    )
+
+    spec = FlaskASTOpenAPI(tmp_path).generate()
+    operation = spec["paths"]["/custom"]["post"]
+
+    assert "application/x-www-form-urlencoded" in operation["requestBody"]["content"]
+    assert "application/problem+json" in operation["responses"]["200"]["content"]