From dd5965fa92f68243db1c3507f8dce249bfa6a508 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristi=20V=C3=AEjdea?= Date: Fri, 21 Dec 2018 18:18:58 +0200 Subject: [PATCH] Fix tuple types in sphinx docstrings --- docs/conf.py | 3 ++- src/drf_yasg/generators.py | 14 ++++++----- src/drf_yasg/inspectors/base.py | 2 +- src/drf_yasg/inspectors/view.py | 4 +-- src/drf_yasg/openapi.py | 44 ++++++++++++++++----------------- src/drf_yasg/utils.py | 37 ++++++++++++++------------- src/drf_yasg/views.py | 2 +- tests/test_schema_generator.py | 4 +-- 8 files changed, 58 insertions(+), 52 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e44703b..d571e5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -171,7 +171,7 @@ nitpick_ignore = [ ('py:class', 'int'), ('py:class', 'bytes'), ('py:class', 'tuple'), - ('py:class', 'callable'), + ('py:class', 'function'), ('py:class', 'type'), ('py:class', 'OrderedDict'), ('py:class', 'None'), @@ -181,6 +181,7 @@ nitpick_ignore = [ ('py:class', 'collections.OrderedDict'), ('py:class', 'ruamel.yaml.dumper.SafeDumper'), + ('py:class', 'rest_framework.serializers.Serializer'), ('py:class', 'rest_framework.renderers.BaseRenderer'), ('py:class', 'rest_framework.schemas.generators.EndpointEnumerator'), ('py:class', 'rest_framework.views.APIView'), diff --git a/src/drf_yasg/generators.py b/src/drf_yasg/generators.py index 345a3ed..db67786 100644 --- a/src/drf_yasg/generators.py +++ b/src/drf_yasg/generators.py @@ -230,8 +230,8 @@ class OpenAPISchemaGenerator(object): def get_schema(self, request=None, public=False): """Generate a :class:`.Swagger` object representing the API schema. - :param Request request: the request used for filtering - accesible endpoints and finding the spec URI + :param request: the request used for filtering accesible endpoints and finding the spec URI + :type request: rest_framework.request.Request or None :param bool public: if True, all endpoints are included regardless of access through `request` :return: the generated Swagger specification @@ -262,9 +262,10 @@ class OpenAPISchemaGenerator(object): def create_view(self, callback, method, request=None): """Create a view instance from a view callback as registered in urlpatterns. - :param callable callback: view callback registered in urlpatterns + :param callback: view callback registered in urlpatterns :param str method: HTTP method - :param rest_framework.request.Request request: request to bind to the view + :param request: request to bind to the view + :type request: rest_framework.request.Request or None :return: the view instance """ view = self._gen.create_view(callback, method, request) @@ -282,9 +283,10 @@ class OpenAPISchemaGenerator(object): def get_endpoints(self, request): """Iterate over all the registered endpoints in the API and return a fake view with the right parameters. - :param rest_framework.request.Request request: request to bind to the endpoint views + :param request: request to bind to the endpoint views + :type request: rest_framework.request.Request or None :return: {path: (view_class, list[(http_method, view_instance)]) - :rtype: dict + :rtype: dict[str,(type,list[(str,rest_framework.views.APIView)])] """ enumerator = self.endpoint_enumerator_class(self._gen.patterns, self._gen.urlconf, request=request) endpoints = enumerator.get_api_endpoints() diff --git a/src/drf_yasg/inspectors/base.py b/src/drf_yasg/inspectors/base.py index 07ffc2c..7c6f11a 100644 --- a/src/drf_yasg/inspectors/base.py +++ b/src/drf_yasg/inspectors/base.py @@ -203,7 +203,7 @@ class FieldInspector(BaseInspector): - :class:`.Schema` if `swagger_object_type` is :class:`.Schema` - :class:`.Items` if `swagger_object_type` is :class:`.Parameter` or :class:`.Items` - :rtype: tuple[callable,(type[openapi.Schema] or type[openapi.Items])] + :rtype: (function,type[openapi.Schema] or type[openapi.Items]) """ assert swagger_object_type in (openapi.Schema, openapi.Parameter, openapi.Items) assert not isinstance(field, openapi.SwaggerDict), "passed field is already a SwaggerDict object" diff --git a/src/drf_yasg/inspectors/view.py b/src/drf_yasg/inspectors/view.py index f226e83..211bd31 100644 --- a/src/drf_yasg/inspectors/view.py +++ b/src/drf_yasg/inspectors/view.py @@ -344,7 +344,7 @@ class SwaggerAutoSchema(ViewInspector): :param description: the full description to be analyzed :return: summary and description - :rtype: tuple[str,str] + :rtype: (str,str) """ # https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings summary = None @@ -362,7 +362,7 @@ class SwaggerAutoSchema(ViewInspector): """Return an operation summary and description determined from the view's docstring. :return: summary and description - :rtype: tuple[str,str] + :rtype: (str,str) """ description = self.overrides.get('operation_description', None) summary = self.overrides.get('operation_summary', None) diff --git a/src/drf_yasg/openapi.py b/src/drf_yasg/openapi.py index 172ceab..e2ac52f 100644 --- a/src/drf_yasg/openapi.py +++ b/src/drf_yasg/openapi.py @@ -246,8 +246,8 @@ class Swagger(SwaggerDict): :param list[dict[str,list[str]]] security: authentication mechanisms accepted globally :param list[str] consumes: consumed MIME types; can be overriden in Operation :param list[str] produces: produced MIME types; can be overriden in Operation - :param .Paths paths: paths object - :param dict[str,.Schema] definitions: named models + :param Paths paths: paths object + :param dict[str,Schema] definitions: named models """ super(Swagger, self).__init__(**extra) self.swagger = '2.0' @@ -298,7 +298,7 @@ class Paths(SwaggerDict): def __init__(self, paths, **extra): """A listing of all the paths in the API. - :param dict[str,.PathItem] paths: + :param dict[str,PathItem] paths: """ super(Paths, self).__init__(**extra) for path, path_obj in paths.items(): @@ -315,14 +315,14 @@ class PathItem(SwaggerDict): head=None, patch=None, parameters=None, **extra): """Information about a single path - :param .Operation get: operation for GET - :param .Operation put: operation for PUT - :param .Operation post: operation for POST - :param .Operation delete: operation for DELETE - :param .Operation options: operation for OPTIONS - :param .Operation head: operation for HEAD - :param .Operation patch: operation for PATCH - :param list[.Parameter] parameters: parameters that apply to all operations + :param Operation get: operation for GET + :param Operation put: operation for PUT + :param Operation post: operation for POST + :param Operation delete: operation for DELETE + :param Operation options: operation for OPTIONS + :param Operation head: operation for HEAD + :param Operation patch: operation for PATCH + :param list[Parameter] parameters: parameters that apply to all operations """ super(PathItem, self).__init__(**extra) self.get = get @@ -351,8 +351,8 @@ class Operation(SwaggerDict): """Information about an API operation (path + http method combination) :param str operation_id: operation ID, should be unique across all operations - :param .Responses responses: responses returned - :param list[.Parameter] parameters: parameters accepted + :param Responses responses: responses returned + :param list[Parameter] parameters: parameters accepted :param list[str] consumes: content types accepted :param list[str] produces: content types produced :param str summary: operation summary; should be < 120 characters @@ -408,7 +408,7 @@ class Parameter(SwaggerDict): :param str description: parameter description :param bool required: whether the parameter is required for the operation :param schema: required if `in_` is ``body`` - :type schema: .Schema or .SchemaRef + :type schema: Schema or SchemaRef :param str type: parameter type; required if `in_` is not ``body``; must not be ``object`` :param str format: value format, see OpenAPI spec :param list enum: restrict possible values @@ -461,12 +461,12 @@ class Schema(SwaggerDict): :param list enum: restrict possible values :param str pattern: pattern if type is ``string`` :param properties: object properties; required if `type` is ``object`` - :type properties: dict[str,(.Schema or .SchemaRef)] + :type properties: dict[str,Schema or SchemaRef] :param additional_properties: allow wildcard properties not listed in `properties` - :type additional_properties: bool or .Schema or .SchemaRef + :type additional_properties: bool or Schema or SchemaRef :param list[str] required: list of requried property names :param items: type of array items, only valid if `type` is ``array`` - :type items: .Schema or .SchemaRef + :type items: Schema or SchemaRef :param default: only valid when insider another ``Schema``\\ 's ``properties``; the default value of this property if it is not provided, must conform to the type of this Schema :param read_only: only valid when insider another ``Schema``\\ 's ``properties``; @@ -565,7 +565,7 @@ def resolve_ref(ref_or_obj, resolver): """Resolve `ref_or_obj` if it is a reference type. Return it unchaged if not. :param ref_or_obj: object to derefernece - :type ref_or_obj: .SwaggerDict or ._Ref + :type ref_or_obj: SwaggerDict or _Ref :param resolver: component resolver which must contain the referenced object """ if isinstance(ref_or_obj, _Ref): @@ -578,8 +578,8 @@ class Responses(SwaggerDict): """Describes the expected responses of an :class:`.Operation`. :param responses: mapping of status code to response definition - :type responses: dict[(str or int),.Response] - :param .Response default: description of the response structure to expect if another status code is returned + :type responses: dict[str or int,Response] + :param Response default: description of the response structure to expect if another status code is returned """ super(Responses, self).__init__(**extra) for status, response in responses.items(): @@ -595,7 +595,7 @@ class Response(SwaggerDict): :param str description: response description :param schema: sturcture of the response body - :type schema: .Schema or .SchemaRef + :type schema: Schema or SchemaRef :param dict examples: example bodies mapped by mime type """ super(Response, self).__init__(**extra) @@ -668,7 +668,7 @@ class ReferenceResolver(object): """Set an object in the given scope only if it does not exist. :param str name: reference name - :param callable maker: object factory, called only if necessary + :param function maker: object factory, called only if necessary :param str scope: reference scope """ scope = self._check_scope(scope) diff --git a/src/drf_yasg/utils.py b/src/drf_yasg/utils.py index 2f7d35b..0486515 100644 --- a/src/drf_yasg/utils.py +++ b/src/drf_yasg/utils.py @@ -39,7 +39,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo :param str method: for multi-method views, the http method the options should apply to :param list[str] methods: for multi-method views, the http methods the options should apply to - :param .inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object; + :param drf_yasg.inspectors.SwaggerAutoSchema auto_schema: custom class to use for generating the Operation object; this overrides both the class-level ``swagger_schema`` attribute and the ``DEFAULT_AUTO_SCHEMA_CLASS`` setting, and can be set to ``None`` to prevent this operation from being generated :param request_body: custom request body which will be used as the ``schema`` property of a @@ -51,10 +51,11 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo If a ``Serializer`` class or instance is given, it will be automatically converted into a :class:`.Schema` used as a ``body`` :class:`.Parameter`, or into a list of ``form`` :class:`.Parameter`\\ s, as appropriate. - :type request_body: .Schema or .SchemaRef or .Serializer or type[.no_body] + :type request_body: drf_yasg.openapi.Schema or drf_yasg.openapi.SchemaRef or rest_framework.serializers.Serializer + or type[no_body] - :param .Serializer query_serializer: if you use a ``Serializer`` to parse query parameters, you can pass it here - and have :class:`.Parameter` objects be generated automatically from it. + :param rest_framework.serializers.Serializer query_serializer: if you use a ``Serializer`` to parse query + parameters, you can pass it here and have :class:`.Parameter` objects be generated automatically from it. If any ``Field`` on the serializer cannot be represented as a ``query`` :class:`.Parameter` (e.g. nested Serializers, file fields, ...), the schema generation will fail with an error. @@ -62,7 +63,8 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo Schema generation will also fail if the name of any Field on the `query_serializer` conflicts with parameters generated by ``filter_backends`` or ``paginator``. - :param list[.Parameter] manual_parameters: a list of manual parameters to override the automatically generated ones + :param list[drf_yasg.openapi.Parameter] manual_parameters: a list of manual parameters to override the + automatically generated ones :class:`.Parameter`\\ s are identified by their (``name``, ``in``) combination, and any parameters given here will fully override automatically generated parameters if they collide. @@ -90,14 +92,15 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo * a ``Serializer`` class or instance will be converted into a :class:`.Schema` and treated as above * a :class:`.Response` object will be used as-is; however if its ``schema`` attribute is a ``Serializer``, it will automatically be converted into a :class:`.Schema` - :type responses: dict[str,(.Schema or .SchemaRef or .Response or str or .Serializer)] + :type responses: dict[str,(drf_yasg.openapi.Schema or drf_yasg.openapi.SchemaRef or drf_yasg.openapi.Response or + str or rest_framework.serializers.Serializer)] - :param list[.FieldInspector] field_inspectors: extra serializer and field inspectors; these will be tried - before :attr:`.ViewInspector.field_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance - :param list[.FilterInspector] filter_inspectors: extra filter inspectors; these will be tried before - :attr:`.ViewInspector.filter_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance - :param list[.PaginatorInspector] paginator_inspectors: extra paginator inspectors; these will be tried before - :attr:`.ViewInspector.paginator_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance + :param list[drf_yasg.inspectors.FieldInspector] field_inspectors: extra serializer and field inspectors; these will + be tried before :attr:`.ViewInspector.field_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance + :param list[drf_yasg.inspectors.FilterInspector] filter_inspectors: extra filter inspectors; these will be tried + before :attr:`.ViewInspector.filter_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance + :param list[drf_yasg.inspectors.PaginatorInspector] paginator_inspectors: extra paginator inspectors; these will be + tried before :attr:`.ViewInspector.paginator_inspectors` on the :class:`.inspectors.SwaggerAutoSchema` instance :param list[str] tags: tags override :param extra_overrides: extra values that will be saved into the ``overrides`` dict; these values will be available in the handling :class:`.inspectors.SwaggerAutoSchema` instance via ``self.overrides`` @@ -249,9 +252,9 @@ def param_list_to_odict(parameters): Raises an ``AssertionError`` if `parameters` contains duplicate parameters (by their name + in combination). - :param list[.Parameter] parameters: the list of parameters + :param list[drf_yasg.openapi.Parameter] parameters: the list of parameters :return: `parameters` keyed by ``(name, in_)`` - :rtype: dict[tuple(str,str),.Parameter] + :rtype: dict[(str,str),drf_yasg.openapi.Parameter] """ result = OrderedDict(((param.name, param.in_), param) for param in parameters) assert len(result) == len(parameters), "duplicate Parameters found" @@ -264,10 +267,10 @@ def merge_params(parameters, overrides): Raises an ``AssertionError`` if either list contains duplicate parameters. - :param list[.Parameter] parameters: initial parameters - :param list[.Parameter] overrides: overriding parameters + :param list[drf_yasg.openapi.Parameter] parameters: initial parameters + :param list[drf_yasg.openapi.Parameter] overrides: overriding parameters :return: merged list - :rtype: list[.Parameter] + :rtype: list[drf_yasg.openapi.Parameter] """ parameters = param_list_to_odict(parameters) parameters.update(param_list_to_odict(overrides)) diff --git a/src/drf_yasg/views.py b/src/drf_yasg/views.py index e091350..256f26c 100644 --- a/src/drf_yasg/views.py +++ b/src/drf_yasg/views.py @@ -62,7 +62,7 @@ def get_schema_view(info=None, url=None, patterns=None, urlconf=None, public=Fal :param tuple authentication_classes: authentication classes for the schema view itself :param tuple permission_classes: permission classes for the schema view itself :return: SchemaView class - :rtype: type[.SchemaView] + :rtype: type[drf_yasg.views.SchemaView] """ _public = public _generator_class = generator_class or swagger_settings.DEFAULT_GENERATOR_CLASS diff --git a/tests/test_schema_generator.py b/tests/test_schema_generator.py index 87b9dfe..d11a552 100644 --- a/tests/test_schema_generator.py +++ b/tests/test_schema_generator.py @@ -1,4 +1,3 @@ -import inspect import json from collections import OrderedDict @@ -156,7 +155,8 @@ def test_url_order(): assert swagger['paths']['/test/']['get']['description'] == 'description override' # get_endpoints only includes one endpoint - assert len(generator.get_endpoints(None)['/test/'][1]) == 1 + endpoints = generator.get_endpoints(None) + assert len(endpoints['/test/'][1]) == 1 try: