Briq
/
drf-yasg
6
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fix tuple types in sphinx docstrings

master
Cristi Vîjdea 2018-12-21 18:18:58 +02:00
parent bfd13668cc
commit dd5965fa92
8 changed files with 58 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/conf.py
View File

@ -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'),

14
src/drf_yasg/generators.py
View File

@ -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()

2
src/drf_yasg/inspectors/base.py
View File

@ -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"

4
src/drf_yasg/inspectors/view.py
View File

@ -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)

44
src/drf_yasg/openapi.py
View File

@ -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)

37
src/drf_yasg/utils.py
View File

@ -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))

2
src/drf_yasg/views.py
View File

@ -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

4
tests/test_schema_generator.py
View File

@ -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: