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

Fix union types in sphinx docstrings

master
Cristi Vîjdea 2018-12-21 14:44:24 +02:00
parent f77672875d
commit db61c39ab1
8 changed files with 36 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.idea/drf-yasg.iml
View File

@ -16,6 +16,8 @@
<content url="file://$MODULE_DIR$">
<sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
<sourceFolder url="file://$MODULE_DIR$/testproj" isTestSource="false" />
<excludeFolder url="file://$MODULE_DIR$/.cache" />
<excludeFolder url="file://$MODULE_DIR$/.eggs" />
<excludeFolder url="file://$MODULE_DIR$/.pytest_cache" />
<excludeFolder url="file://$MODULE_DIR$/build" />
<excludeFolder url="file://$MODULE_DIR$/dist" />

1
docs/conf.py
View File

@ -175,6 +175,7 @@ nitpick_ignore = [
('py:class', 'type'),
('py:class', 'OrderedDict'),
('py:class', 'None'),
('py:obj', 'None'),
('py:class', 'Exception'),
('py:class', 'collections.OrderedDict'),

2
src/drf_yasg/codecs.py
View File

@ -170,7 +170,7 @@ def yaml_sane_dump(data, binary):
:param dict data: the data to be dumped
:param bool binary: True to return a utf-8 encoded binary object, False to return a string
:return: the serialized YAML
:rtype: str,bytes
:rtype: str or bytes
"""
return yaml.dump(data, Dumper=SaneYamlDumper, default_flow_style=False, encoding='utf-8' if binary else None)

4
src/drf_yasg/generators.py
View File

@ -203,7 +203,7 @@ class OpenAPISchemaGenerator(object):
and helps clients configure their authorization credentials.
:return: the security schemes usable with this API
:rtype: dict[str,dict]|None
:rtype: dict[str,dict] or None
"""
security_definitions = swagger_settings.SECURITY_DEFINITIONS
if security_definitions is not None:
@ -217,7 +217,7 @@ class OpenAPISchemaGenerator(object):
:param security_definitions: security definitions as returned by :meth:`.get_security_definitions`
:return:
:rtype: dict[str,list[str]]|None
:rtype: list[dict[str,list[str]]] or None
"""
security_requirements = swagger_settings.SECURITY_REQUIREMENTS
if security_requirements is None:

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

@ -159,7 +159,7 @@ class FieldInspector(BaseInspector):
:param kwargs: extra attributes for constructing the object;
if swagger_object_type is Parameter, ``name`` and ``in_`` should be provided
:return: the swagger object
:rtype: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
:rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef
"""
return NotHandled
@ -168,7 +168,7 @@ class FieldInspector(BaseInspector):
All arguments are the same as :meth:`.field_to_swagger_object`.
:rtype: openapi.Parameter,openapi.Items,openapi.Schema,openapi.SchemaRef
:rtype: openapi.Parameter or openapi.Items or openapi.Schema or openapi.SchemaRef
"""
return self.probe_inspectors(
self.field_inspectors, 'field_to_swagger_object', field, {'field_inspectors': self.field_inspectors},
@ -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],type[openapi.Items])]
:rtype: tuple[callable,(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"
@ -368,7 +368,7 @@ class ViewInspector(BaseInspector):
:param serializers.BaseSerializer serializer: the ``Serializer`` instance
:returns: the converted :class:`.Schema`, or ``None`` in case of an unknown serializer
:rtype: openapi.Schema,openapi.SchemaRef
:rtype: openapi.Schema or openapi.SchemaRef
"""
return self.probe_inspectors(
self.field_inspectors, 'get_schema', serializer, {'field_inspectors': self.field_inspectors}

29
src/drf_yasg/openapi.py
View File

@ -237,8 +237,8 @@ class Swagger(SwaggerDict):
:param str _prefix: api path prefix to use in setting basePath; this will be appended to the wsgi
SCRIPT_NAME prefix or Django's FORCE_SCRIPT_NAME if applicable
:param str _version: version string to override Info
:param dict[str,dict[str,str]] security_definitions: list of supported authentication mechanisms
:param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation
:param dict[str,dict] security_definitions: list of supported authentication mechanisms
: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
@ -402,7 +402,8 @@ class Parameter(SwaggerDict):
:param str in_: parameter location
:param str description: parameter description
:param bool required: whether the parameter is required for the operation
:param .Schema,.SchemaRef schema: required if `in_` is ``body``
:param schema: required if `in_` is ``body``
: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
@ -454,10 +455,13 @@ class Schema(SwaggerDict):
:param str format: value format, see OpenAPI spec
:param list enum: restrict possible values
:param str pattern: pattern if type is ``string``
:param dict[str,(.Schema,.SchemaRef)] properties: object properties; required if `type` is ``object``
:param bool,.Schema,.SchemaRef additional_properties: allow wildcard properties not listed in `properties`
:param properties: object properties; required if `type` is ``object``
: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
:param list[str] required: list of requried property names
:param .Schema,.SchemaRef items: type of array items, only valid if `type` is ``array``
:param items: type of array items, only valid if `type` is ``array``
: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``;
@ -508,7 +512,7 @@ class _Ref(SwaggerDict):
:param str name: referenced object name, e.g. "Article"
:param str scope: reference scope, e.g. "definitions"
:param type[.SwaggerDict] expected_type: the expected type that will be asserted on the object found in resolver
:param bool ignore_unresolved: allow the reference to be not defined in resolver
:param bool ignore_unresolved: do not throw if the referenced object does not exist
"""
super(_Ref, self).__init__()
assert not type(self) == _Ref, "do not instantiate _Ref directly"
@ -543,7 +547,7 @@ class SchemaRef(_Ref):
:param .ReferenceResolver resolver: component resolver which must contain the definition
:param str schema_name: schema name
:param bool ignore_unresolved: allow the reference to be not defined in resolver
:param bool ignore_unresolved: do not throw if the referenced object does not exist
"""
assert SCHEMA_DEFINITIONS in resolver.scopes
super(SchemaRef, self).__init__(resolver, schema_name, SCHEMA_DEFINITIONS, Schema, ignore_unresolved)
@ -555,7 +559,8 @@ Schema.OR_REF = (Schema, SchemaRef)
def resolve_ref(ref_or_obj, resolver):
"""Resolve `ref_or_obj` if it is a reference type. Return it unchaged if not.
:param SwaggerDict,_Ref ref_or_obj:
:param ref_or_obj: object to derefernece
:type ref_or_obj: .SwaggerDict or ._Ref
:param resolver: component resolver which must contain the referenced object
"""
if isinstance(ref_or_obj, _Ref):
@ -567,7 +572,8 @@ class Responses(SwaggerDict):
def __init__(self, responses, default=None, **extra):
"""Describes the expected responses of an :class:`.Operation`.
:param dict[(str,int),.Response] responses: mapping of status code to response definition
: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
"""
super(Responses, self).__init__(**extra)
@ -583,7 +589,8 @@ class Response(SwaggerDict):
"""Describes the structure of an operation's response.
:param str description: response description
:param .Schema,.SchemaRef schema: sturcture of the response body
:param schema: sturcture of the response body
:type schema: .Schema or .SchemaRef
:param dict examples: example bodies mapped by mime type
"""
super(Response, self).__init__(**extra)

8
src/drf_yasg/utils.py
View File

@ -42,8 +42,8 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
:param .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 .Schema,.SchemaRef,.Serializer request_body: custom request body, or :class:`.no_body`. The value given here
will be used as the ``schema`` property of a :class:`.Parameter` with ``in: 'body'``.
:param request_body: custom request body which will be used as the ``schema`` property of a
:class:`.Parameter` with ``in: 'body'``.
A Schema or SchemaRef is not valid if this request consumes form-data, because ``form`` and ``body`` parameters
are mutually exclusive in an :class:`.Operation`. If you need to set custom ``form`` parameters, you can use
@ -51,6 +51,7 @@ 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]
: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.
@ -75,7 +76,7 @@ def swagger_auto_schema(method=None, methods=None, auto_schema=unset, request_bo
is requried to call this API; an empty list marks the endpoint as unauthenticated (i.e. removes all accepted
authentication schemes), and ``None`` will inherit the top-level secuirty requirements
:param bool deprecated: deprecation status for operation
:param dict[str,(.Schema,.SchemaRef,.Response,str,Serializer)] responses: a dict of documented manual responses
:param responses: a dict of documented manual responses
keyed on response status code. If no success (``2xx``) response is given, one will automatically be
generated from the request body and http method. If any ``2xx`` response is given the automatic response is
suppressed.
@ -89,6 +90,7 @@ 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)]
: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

5
tox.ini
View File

@ -1,8 +1,9 @@
[tox]
# https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
minversion = 3.3.0
isolated_build = true
isolated_build_env=.package
# https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
envlist =
py{27,34,35,36}-django111-drf{37,38,39},
py{34,35,36,37}-django20-drf{37,38,39},
@ -72,5 +73,5 @@ known_standard_library =
known_third_party =
coreapi,coreschema,datadiff,dj_database_url,django,django_filters,djangorestframework_camel_case,
rest_framework_recursive,flex,gunicorn,inflection,pygments,pytest,rest_framework,ruamel,setuptools_scm,
swagger_spec_validator,uritemplate,user_agents,whitenoise
swagger_spec_validator,uritemplate,user_agents,whitenoise,oauth2_provider
known_first_party = drf_yasg,testproj,articles,people,snippets,todo,users,urlconfs