validate_update() is deprecated.

nicolaiarocci · nicolaiarocci · commit 2fd6bfe8ebca · 2013-09-23T09:02:53.000+02:00
Use validate() with 'update=True' instead. Closes pyeve#21.
diff --git a/CHANGES b/CHANGES
@@ -8,6 +8,8 @@ Version 0.4.0
 
 Not released yet.
 
+- 'validate_update' is deprecated and will be removed with next release. Use
+  'validate' with 'update=True' instead. Closes #21.
 - Fixed a minor encoding issue which made installing on Windows/Python3
   impossible. Closes #19 (Arsh Singh).
 - Fix documentation typo (Daniele Pizzolli).
@@ -32,14 +34,14 @@ Released on July 9 2013.
 Version 0.2.0
 -------------
 
-Released on April 18 2013. 
+Released on April 18 2013.
 
 - 'allow_unknown' option added.
 
 Version 0.1.0
 -------------
 
-Released on March 15 2013. 
+Released on March 15 2013.
 Codename: 'Claw'.
 
 - entering beta phase.
@@ -56,7 +58,7 @@ Version 0.0.3
 
 Released on January 29 2013
 
-- when a list item fails, its offset is now returned along with the list name 
+- when a list item fails, its offset is now returned along with the list name.
 - 'transparent_schema_rules' option added.
 - 'empty' rule for string fields.
 - 'schema' rule on lists of arbitrary lenght (Martjin Vermaat).
diff --git a/cerberus/cerberus.py b/cerberus/cerberus.py
@@ -34,10 +34,9 @@ class SchemaError(ValueError):
 
 
 class Validator(object):
-    """ Validator class. Validates any Python dict
-    against a validation schema, which is provided as an argument at
-    class instantiation, or upon calling the :func:`validate` or
-    :func:`validate_update` methods.
+    """ Validator class. Validates any Python dict against a validation schema,
+    which is provided as an argument at class instantiation, or upon calling
+    the :func:`validate` method.
 
     :param schema: optional validation schema.
     :param transparent_schema_rules: if ``True`` unknown schema rules will be
@@ -55,9 +54,11 @@ class instantiation, or upon calling the :func:`validate` or
                           field error' un validation.
 
     .. versionchanged:: 0.4.0
-       'type' validation is always performed first (only exception being
-       'nullable'). On failure, it blocks other rules on the same field. Closes
-       #18.
+       :func:`validate_update` is deprecated. Use :func:`validate` with
+       ``update=True`` instead.
+       Type validation is always performed first (only exception being
+       ``nullable``). On failure, it blocks other rules on the same field.
+       Closes #18.
 
     .. versionadded:: 0.2.0
        `self.errors` returns an empty list when validate() has not been called.
@@ -87,8 +88,7 @@ def __init__(self, schema=None, transparent_schema_rules=False,
     def errors(self):
         """
         :rtype: a list of validation errors. Will be empty if no errors
-                were found during. Resets after each call to :func:`validate`
-                or :func:`validate_update`.
+                were found during. Resets after each call to :func:`validate`.
         """
         return self._errors
 
@@ -102,21 +102,29 @@ def validate_update(self, document, schema=None):
                        class instantation.
         :return: True if validation succeeds, False otherwise. Check the
                  :func:`errors` property for a list of validation errors.
+
+        .. deprecated:: 0.4.0
+           Use :func:`validate` with ``update=True`` instead.
         """
         return self._validate(document, schema, update=True)
 
-    def validate(self, document, schema=None):
+    def validate(self, document, schema=None, update=False):
         """ Validates a Python dictionary against a validation schema.
 
         :param document: the dict to validate.
         :param schema: the validation schema. Defaults to ``None``. If not
                        provided here, the schema must have been provided at
                        class instantation.
+        :param update: If ``True`` validation of required fields won't be
+                       performed.
 
         :return: True if validation succeeds, False otherwise. Check the
                  :func:`errors` property for a list of validation errors.
+
+        .. versionchanged:: 0.4.0
+           Support for update mode.
         """
-        return self._validate(document, schema, update=False)
+        return self._validate(document, schema, update=update)
 
     def _validate(self, document, schema=None, update=False):
 
diff --git a/cerberus/tests/__init__.py b/cerberus/tests/__init__.py
@@ -111,7 +111,7 @@ def assertFail(self, document, schema=None, validator=None):
     def assertSuccess(self, document, schema=None, validator=None):
         if validator is None:
             validator = self.validator
-        self.assertTrue(validator.validate_update(document, schema))
+        self.assertTrue(validator.validate(document, schema, update=True))
 
     def assertError(self, error, validator=None):
         if validator is None:
diff --git a/cerberus/tests/tests.py b/cerberus/tests/tests.py
@@ -190,7 +190,8 @@ def test_string_unallowed(self):
         self.assertError(errors.ERROR_UNALLOWED_VALUE % (value, field))
 
     def test_validate_update(self):
-        self.assertTrue(self.validator.validate_update({'an_integer': 100}))
+        self.assertTrue(self.validator.validate({'an_integer': 100},
+                                                update=True))
 
     def test_string(self):
         self.assertSuccess({'a_required_string': 'john doe'})
diff --git a/docs/index.rst b/docs/index.rst
@@ -20,9 +20,10 @@ You define a validation schema and pass it to an instance of the
     >>> schema = {'name': {'type': 'string'}}
     >>> v = Validator(schema)
 
-Then you simply invoke the :func:`~cerberus.Validator.validate` or
-:func:`~cerberus.Validator.validate_update` methods to validate a dictionary
-against the schema. If validation succeeds, ``True`` is returned: ::
+Then you simply invoke the :func:`~cerberus.Validator.validate` to validate
+a dictionary against the schema. If validation succeeds, ``True`` is returned:
+
+::
 
     >>> document = {'name': 'john doe'}
     >>> v.validate(document)
@@ -189,10 +190,11 @@ You can extend this list and support custom types, see :ref:`new-types`.
 
 required
 ''''''''
-If ``True`` the key/value pair is mandatory and validation will fail when
-:func:`~cerberus.Validator.validate` is called.  Validation will still succeed
-if the value is missing and :func:`~cerberus.Validator.validate_update` is
-called instead.::
+If ``True`` the key/value pair is mandatory. Validation will fail when it is
+missing, unless :func:`~cerberus.Validator.validate` is called with
+``update=True``:
+
+::
 
     >>> schema = {'name': {'required': True, 'type': 'string'}, 'age': {'type': 'integer'}}
     >>> v = Validator(schema)
@@ -202,7 +204,7 @@ called instead.::
     >>> v.errors
     ["required field(s) are missing: 'name'"]
 
-    >>> v.validate_update(document)
+    >>> v.validate(document, update=True)
     True
 
 .. note::
