Merge pull request #765 from marshmallow-code/fix_typing

Fix typing for APISpec.path path parameter and Plugin methods

.pre-commit-config.yaml

@@ -23,5 +23,4 @@ repos:
   rev: v0.950
   hooks:
   - id: mypy
-    files: ^src/apispec/
     additional_dependencies: ["marshmallow>=3,<4", "types-PyYAML"]

src/apispec/core.py

@@ -1,6 +1,8 @@
 """Core apispec classes and functions."""
 
 from __future__ import annotations
+from collections.abc import Sequence
+
 
 import typing
 from copy import deepcopy
@@ -15,6 +17,10 @@
 )
 from .utils import OpenAPIVersion, deepupdate, COMPONENT_SUBSECTIONS, build_reference
 
+if typing.TYPE_CHECKING:
+    from .plugin import BasePlugin
+
+
 VALID_METHODS_OPENAPI_V2 = ["get", "post", "put", "patch", "delete", "head", "options"]
 
 VALID_METHODS_OPENAPI_V3 = VALID_METHODS_OPENAPI_V2 + ["trace"]
@@ -31,7 +37,7 @@ class Components:
 
     def __init__(
         self,
-        plugins: tuple | list,
+        plugins: Sequence[BasePlugin],
         openapi_version: OpenAPIVersion,
     ) -> None:
         self._plugins = plugins
@@ -410,7 +416,7 @@ def __init__(
         title: str,
         version: str,
         openapi_version: OpenAPIVersion | str,
-        plugins: tuple | list = (),
+        plugins: Sequence[BasePlugin] = (),
         **options: typing.Any,
     ) -> None:
         self.title = title
@@ -467,7 +473,7 @@ def tag(self, tag: dict) -> APISpec:
 
     def path(
         self,
-        path: dict | None = None,
+        path: str | None = None,
         *,
         operations: dict[str, typing.Any] | None = None,
         summary: str | None = None,

src/apispec/plugin.py

@@ -17,7 +17,9 @@ def init_spec(self, spec: APISpec) -> None:
         :param APISpec spec: APISpec object this plugin instance is attached to
         """
 
-    def schema_helper(self, name: str, definition: dict, **kwargs: typing.Any) -> None:
+    def schema_helper(
+        self, name: str, definition: dict, **kwargs: typing.Any
+    ) -> dict | None:
         """May return definition as a dict.
 
         :param str name: Identifier by which schema may be referenced
@@ -26,23 +28,23 @@ def schema_helper(self, name: str, definition: dict, **kwargs: typing.Any) -> No
         """
         raise PluginMethodNotImplementedError
 
-    def response_helper(self, response: dict, **kwargs: typing.Any) -> None:
+    def response_helper(self, response: dict, **kwargs: typing.Any) -> dict | None:
         """May return response component description as a dict.
 
         :param dict response: Response fields
         :param kwargs: All additional keywords arguments sent to `APISpec.response()`
         """
         raise PluginMethodNotImplementedError
 
-    def parameter_helper(self, parameter: dict, **kwargs: typing.Any) -> None:
+    def parameter_helper(self, parameter: dict, **kwargs: typing.Any) -> dict | None:
         """May return parameter component description as a dict.
 
         :param dict parameter: Parameter fields
         :param kwargs: All additional keywords arguments sent to `APISpec.parameter()`
         """
         raise PluginMethodNotImplementedError
 
-    def header_helper(self, header: dict, **kwargs: typing.Any) -> None:
+    def header_helper(self, header: dict, **kwargs: typing.Any) -> dict | None:
         """May return header component description as a dict.
 
         :param dict header: Header fields
@@ -56,7 +58,7 @@ def path_helper(
         operations: dict | None = None,
         parameters: list[dict] | None = None,
         **kwargs: typing.Any,
-    ) -> None:
+    ) -> str | None:
         """May return a path as string and mutate operations dict and parameters list.
 
         :param str path: Path to the resource

tests/schemas.py

@@ -43,7 +43,7 @@ class PatternedObjectSchema(Schema):
 class SelfReferencingSchema(Schema):
     id = fields.Int()
     single = fields.Nested(lambda: SelfReferencingSchema())
-    many = fields.Nested(lambda: SelfReferencingSchema(many=True))
+    multiple = fields.Nested(lambda: SelfReferencingSchema(many=True))
 
 
 class OrderedSchema(Schema):

tests/test_ext_marshmallow.py

@@ -1237,7 +1237,7 @@ def test_self_referencing_field_single(self, spec):
     def test_self_referencing_field_many(self, spec):
         spec.components.schema("SelfReference", schema=SelfReferencingSchema)
         definitions = get_schemas(spec)
-        result = definitions["SelfReference"]["properties"]["many"]
+        result = definitions["SelfReference"]["properties"]["multiple"]
         assert result == {
             "type": "array",
             "items": build_ref(spec, "schema", "SelfReference"),