griffe-fastapi 0.1.0__tar.gz

griffe_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.1
+Name: griffe-fastapi
+Version: 0.1.0
+Summary: Griffe extension for FastAPI.
+Author: fbraem
+Author-email: franky.braem@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: griffe (>=1.5.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+Griffe FastAPI Extension
+========================
+
+This extension will search for functions that are decorated with an APIRouter and adds the following extra
+fields to a function:
+
++ method: the HTTP method
++ responses: A dictionary with the responses
+
+These fields are stored in the extra property of the function. The extra property is a dictionary and `griffe_fastapi`
+is the key for the fields of this extension.
+
+Create a custom function template to handle these extra fields in your documentation.
+

griffe_fastapi-0.1.0/README.md

@@ -0,0 +1,13 @@
+Griffe FastAPI Extension
+========================
+
+This extension will search for functions that are decorated with an APIRouter and adds the following extra
+fields to a function:
+
++ method: the HTTP method
++ responses: A dictionary with the responses
+
+These fields are stored in the extra property of the function. The extra property is a dictionary and `griffe_fastapi`
+is the key for the fields of this extension.
+
+Create a custom function template to handle these extra fields in your documentation.

griffe_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "griffe-fastapi"
+version = "0.1.0"
+description = "Griffe extension for FastAPI."
+authors = ["fbraem <franky.braem@gmail.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+griffe = "^1.5.1"
+
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.3"
+
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.7.4"
+black = "^24.10.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

griffe_fastapi-0.1.0/src/griffe_fastapi/__init__.py

@@ -0,0 +1,8 @@
+"""griffe-fastapi package.
+
+Griffe extension for FastAPI.
+"""
+
+from griffe_fastapi._extension import FastAPIExtension
+
+__all__: list[str] = ["FastAPIExtension"]

griffe_fastapi-0.1.0/src/griffe_fastapi/_extension.py

@@ -0,0 +1,155 @@
+"""griffe_fastapi extension."""
+
+import ast
+from typing import Any
+from griffe import (
+    Decorator,
+    ExprAttribute,
+    ExprDict,
+    ExprKeyword,
+    ExprName,
+    Extension,
+    Function,
+    Inspector,
+    ObjectNode,
+    Visitor,
+    get_logger,
+)
+
+self_namespace = "griffe_fastapi"
+
+logger = get_logger(__name__)
+
+
+def _search_decorator(decorators: list[Decorator]) -> Decorator | None:
+    """Search for a APIRouter decorator."""
+    decorators = list(
+        filter(
+            lambda d: d.value.canonical_name in ("get", "post", "patch", "delete"),
+            decorators,
+        )
+    )
+    if len(decorators) == 0:
+        return None
+
+    for decorator in decorators:
+        module = decorator.value.function.first.parent
+        if decorator.value.function.first.name not in module.members:
+            logger.warning(
+                f"Cannot find {decorator.value.function.first.name} in module {module.name}"
+            )
+            return None
+
+        type_ = module.members[decorator.value.function.first.name].value.canonical_name
+        if type_ == "APIRouter":
+            return decorator
+
+    return None
+
+
+def _process_responses(
+    func: Function,
+    http_code_attribute: str | ExprAttribute,
+    open_api_response: ExprName | ExprDict,
+):
+    """Process the response code and the response object."""
+    http_code = None
+    # When a constant is used, resolve the value
+    if isinstance(http_code_attribute, ExprAttribute):
+        if http_code_attribute.canonical_path.startswith("fastapi.status."):
+            http_code = http_code_attribute.last.name.split("_")[1]
+        if http_code is None:
+            logger.warning(
+                f"Could not resolve http code {http_code_attribute.canonical_path} "
+                f"for function {func.canonical_path}"
+            )
+            return
+    else:
+        http_code = http_code_attribute
+
+    func.extra[self_namespace]["responses"][http_code] = {
+        ast.literal_eval(str(key)): ast.literal_eval(str(value))
+        for key, value in zip(
+            open_api_response.keys,
+            open_api_response.values,
+            strict=True,
+        )
+    }
+
+
+class FastAPIExtension(Extension):
+    def __init__(self, *, paths: list[str] | None = None):
+        """Initialize the extension.
+
+        When paths are set, the extension will only process the modules of the given
+        path.
+        """
+        super().__init__()
+        self._paths = paths or []
+
+    def on_function_instance(
+        self,
+        *,
+        node: ast.AST | ObjectNode,
+        func: Function,
+        agent: Visitor | Inspector,
+        **kwargs: Any,
+    ) -> None:
+        """Implement the function instance handler."""
+
+        # When paths is set, skip functions that are not part of the path.
+        if self._paths:
+            if not any(func.path.startswith(path) for path in self._paths):
+                return
+
+        decorator = _search_decorator(func.decorators)
+        if decorator is None:
+            return
+
+        func.extra[self_namespace] = {"method": decorator.value.canonical_name}
+
+        # Search the "responses" keyword in the arguments of the function.
+        responses = next(
+            (
+                x
+                for x in decorator.value.arguments
+                if isinstance(x, ExprKeyword) and x.name == "responses"
+            ),
+            None,
+        )
+        if responses is None:
+            logger.warning(
+                f"No responses argument found for function {func.canonical_path}"
+            )
+            return
+        if not isinstance(responses.value, ExprDict):
+            logger.warning(
+                f"responses argument is not a dict for function {func.canonical_path}"
+            )
+            return
+
+        resolved_responses = {}
+
+        for http_code_variable, open_api_response_obj in zip(
+            responses.value.keys, responses.value.values, strict=True
+        ):
+            # When the response contains a variable, try to resolve it.
+            if isinstance(open_api_response_obj, ExprName):
+                module_attribute = func.module.members[open_api_response_obj.name]
+                if isinstance(module_attribute.value, ExprDict):
+                    resolved_responses = {
+                        **resolved_responses,
+                        **{
+                            k: v
+                            for k, v in zip(
+                                module_attribute.value.keys,
+                                module_attribute.value.values,
+                            )
+                        },
+                    }
+            else:
+                resolved_responses[http_code_variable] = open_api_response_obj
+
+        func.extra[self_namespace]["responses"] = {}
+        for key, value in resolved_responses.items():
+            _process_responses(func, key, value)