Fix union types in sphinx docstrings

.idea/drf-yasg.iml

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

docs/conf.py

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

src/drf_yasg/codecs.py

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

src/drf_yasg/generators.py

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

src/drf_yasg/inspectors/base.py

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

src/drf_yasg/openapi.py

@@ -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 dict[str,dict] security_definitions: list of supported authentication mechanisms
-        :param list[dict] security: authentication mechanisms accepted by default; can be overriden in Operation
+        :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 properties: object properties; required if `type` is ``object``
-        :param bool,.Schema,.SchemaRef additional_properties: allow wildcard properties not listed in `properties`
+        :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)

src/drf_yasg/utils.py

@@ -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
+    :param request_body: custom request body which will be used as the ``schema`` property of a
-        will be used as the ``schema`` property of a :class:`.Parameter` with ``in: 'body'``.
+        :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

tox.ini

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