From 9b46129e4016012b6cd841d2c4910c00d0764fde Mon Sep 17 00:00:00 2001 From: Julian Berman Date: Sun, 27 Nov 2016 10:40:58 -0500 Subject: [PATCH] Napoleon. --- docs/conf.py | 1 + jsonschema/_format.py | 63 ++++++++++++---- jsonschema/_utils.py | 6 +- jsonschema/tests/test_validators.py | 2 +- jsonschema/validators.py | 113 ++++++++++++++++++++++------ 5 files changed, 142 insertions(+), 43 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c52a839..ffacdaa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,6 +23,7 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'jsonschema_role', ] diff --git a/jsonschema/_format.py b/jsonschema/_format.py index 9ad0063..bd2f95d 100644 --- a/jsonschema/_format.py +++ b/jsonschema/_format.py @@ -21,9 +21,12 @@ class FormatChecker(object): returns a ``bool``, use the :meth:`FormatChecker.checks` or :meth:`FormatChecker.cls_checks` decorators. - :argument iterable formats: the known formats to validate. This argument - can be used to limit which formats will be used - during validation. + Arguments: + + formats (iterable): + + The known formats to validate. This argument can be used to + limit which formats will be used during validation. """ @@ -39,11 +42,20 @@ class FormatChecker(object): """ Register a decorated function as validating a new format. - :argument str format: the format that the decorated function will check - :argument Exception raises: the exception(s) raised by the decorated - function when an invalid instance is found. The exception object - will be accessible as the :attr:`ValidationError.cause` attribute - of the resulting validation error. + Arguments: + + format (str): + + The format that the decorated function will check. + + raises (Exception): + + The exception(s) raised by the decorated function when + an invalid instance is found. + + The exception object will be accessible as the + :attr:`ValidationError.cause` attribute of the resulting + validation error. """ @@ -58,10 +70,20 @@ class FormatChecker(object): """ Check whether the instance conforms to the given format. - :argument instance: the instance to check - :type: any primitive type (str, number, bool) - :argument str format: the format that instance should conform to - :raises: :exc:`FormatError` if instance does not conform to format + Arguments: + + instance (any primitive type, i.e. str, number, bool): + + The instance to check + + format (str): + + The format that instance should conform to + + + Raises: + + :exc:`FormatError` if instance does not conform to ``format`` """ @@ -83,10 +105,19 @@ class FormatChecker(object): """ Check whether the instance conforms to the given format. - :argument instance: the instance to check - :type: any primitive type (str, number, bool) - :argument str format: the format that instance should conform to - :rtype: bool + Arguments: + + instance (any primitive type, i.e. str, number, bool): + + The instance to check + + format (str): + + The format that instance should conform to + + Returns: + + bool: Whether it conformed """ diff --git a/jsonschema/_utils.py b/jsonschema/_utils.py index ae7e2b5..7b1c33a 100644 --- a/jsonschema/_utils.py +++ b/jsonschema/_utils.py @@ -73,7 +73,11 @@ def format_as_index(indices): For example, [1, 2, "foo"] -> [1][2]["foo"] - :type indices: sequence + Arguments: + + indices (sequence): + + The indices to format. """ diff --git a/jsonschema/tests/test_validators.py b/jsonschema/tests/test_validators.py index 84ba660..f281161 100644 --- a/jsonschema/tests/test_validators.py +++ b/jsonschema/tests/test_validators.py @@ -929,6 +929,6 @@ def sorted_errors(errors): def key(error): return ( [str(e) for e in error.path], - [str(e) for e in error.schema_path] + [str(e) for e in error.schema_path], ) return sorted(errors, key=key) diff --git a/jsonschema/validators.py b/jsonschema/validators.py index 0945949..29e1b12 100644 --- a/jsonschema/validators.py +++ b/jsonschema/validators.py @@ -31,8 +31,15 @@ def validates(version): Registered validators and their meta schemas will be considered when parsing ``$schema`` properties' URIs. - :argument str version: an identifier to use as the version's name - :returns: a class decorator to decorate the validator with the version + Arguments: + + version (str): + + An identifier to use as the version's name + + Returns: + + callable: a class decorator to decorate the validator with the version """ @@ -226,17 +233,38 @@ class RefResolver(object): """ Resolve JSON References. - :argument str base_uri: URI of the referring document - :argument referrer: the actual referring document - :argument dict store: a mapping from URIs to documents to cache - :argument bool cache_remote: whether remote refs should be cached after - first resolution - :argument dict handlers: a mapping from URI schemes to functions that - should be used to retrieve them - :arguments functools.lru_cache urljoin_cache: a cache that will be used for - caching the results of joining the resolution scope to subscopes. - :arguments functools.lru_cache remote_cache: a cache that will be used for - caching the results of resolved remote URLs. + Arguments: + + base_uri (str): + + The URI of the referring document + + referrer: + + The actual referring document + + store (dict): + + A mapping from URIs to documents to cache + + cache_remote (bool): + + Whether remote refs should be cached after first resolution + + handlers (dict): + + A mapping from URI schemes to functions that should be used + to retrieve them + + urljoin_cache (functools.lru_cache): + + A cache that will be used for caching the results of joining + the resolution scope to subscopes. + + remote_cache (functools.lru_cache): + + A cache that will be used for caching the results of + resolved remote URLs. """ @@ -275,8 +303,15 @@ class RefResolver(object): """ Construct a resolver from a JSON schema object. - :argument schema: the referring schema - :rtype: :class:`RefResolver` + Arguments: + + schema: + + the referring schema + + Returns: + + :class:`RefResolver` """ @@ -320,7 +355,11 @@ class RefResolver(object): Context manager which resolves a JSON ``ref`` and enters the resolution scope of this ref. - :argument str ref: reference to resolve + Arguments: + + ref (str): + + The reference to resolve """ @@ -351,8 +390,15 @@ class RefResolver(object): """ Resolve a ``fragment`` within the referenced ``document``. - :argument document: the referrant document - :argument str fragment: a URI fragment to resolve within it + Arguments: + + document: + + The referrant document + + fragment (str): + + a URI fragment to resolve within it """ @@ -394,8 +440,15 @@ class RefResolver(object): If it isn't, or if the scheme of the ``uri`` is not ``http`` or ``https``, UTF-8 is assumed. - :argument str uri: the URI to resolve - :returns: the retrieved document + Arguments: + + uri (str): + + The URI to resolve + + Returns: + + The retrieved document .. _requests: http://pypi.python.org/pypi/requests/ @@ -448,10 +501,19 @@ def validate(instance, schema, cls=None, *args, **kwargs): (e.g. :meth:`Draft4Validator.validate`). - :argument instance: the instance to validate - :argument schema: the schema to validate with - :argument cls: an :class:`IValidator` class that will be used to validate - the instance. + Arguments: + + instance: + + The instance to validate + + schema: + + The schema to validate with + + cls (:class:`IValidator`): + + The class that will be used to validate the instance. If the ``cls`` argument is not provided, two things will happen in accordance with the specification. First, if the schema has a @@ -464,7 +526,8 @@ def validate(instance, schema, cls=None, *args, **kwargs): Any other provided positional and keyword arguments will be passed on when instantiating the ``cls``. - :raises: + Raises: + :exc:`ValidationError` if the instance is invalid :exc:`SchemaError` if the schema itself is invalid