documented validators

README.md

@@ -117,6 +117,33 @@ class Person(Document):
 
 > If you do not specify an "id" field, ESEngine will automatically add "id" as StringField. It is recommended that when specifying you use StringField for ids.
 
+
+## Special Fields
+
+### GeoField
+
+A field to hold GeoPoint with modes dict|array|string and its mappings
+
+```python
+class Obj(Document):
+    location = GeoField(mode='dict')  # default
+    # An object representation with lat and lon explicitly named
+
+Obj.location = {"lat": 40.722, "lon": -73.989}}
+
+class Obj(Document):
+    location = GeoField(mode='string')
+    # A string representation, with "lat,lon"
+
+Obj.location = "40.715, -74.011"
+
+class Obj(Document):
+    location = GeoField(mode='array')
+    # An array representation with [lon,lat].
+
+Obj.location = [-73.983, 40.719]
+```
+
 ## Indexing
 
 ```python
@@ -386,6 +413,59 @@ Person.update_all(
 
 TODO:
 
+
+#### Validators
+
+##### Field Validator
+
+To validate each field separately you can set a list of validators, each 
+validator is a callable receiving field_name and value as arguments and
+should return None to be valid. If raise or return the data will be invalidated
+
+```python
+from esengine.exceptions import ValidationError
+
+def category_validator(field_name, value):
+    # check if value is in valid categories
+    if value not in ["primary", "secondary", ...]:
+        raise ValidationError("Invalid category!!!")
+
+class Obj(Document):
+    category = StringField(validators=[category_validator])
+
+obj = Obj()
+obj.category = "another"
+obj.save()
+Traceback: ValidationError(....)
+
+```
+
+##### Document Validator
+
+To validate the whole document you can set a list of validators, each 
+validator is a callable receiving the document instance and
+should return None to be valid. If raise or return the data will be invalidated
+
+```python
+from esengine.exceptions import ValidationError
+
+def if_city_state_is_required(obj):
+    if obj.city and not obj.state:
+        raise ValidationError("If city is defined you should define state")
+
+class Obj(Document):
+    _validators = [if_city_state_is_required]
+
+    city = StringField()
+    state = StringField()
+
+obj = Obj()
+obj.city = "Sao Paulo"
+obj.save()
+Traceback: ValidationError(....)
+
+```
+
 #### Refreshing
 
 Sometimes you need to force indices-shards refresh for testing, you can use

esengine/fields.py

@@ -1,12 +1,14 @@
-__all__ = [
-    'IntegerField', 'StringField', 'FloatField',
-    'DateField', 'BooleanField', 'GeoField'
-]
+# coding: utf-8
 
 from datetime import datetime
 from esengine.bases.field import BaseField
 from esengine.exceptions import ValidationError
 
+__all__ = [
+    'IntegerField', 'StringField', 'FloatField',
+    'DateField', 'BooleanField', 'GeoField'
+]
+
 
 class IntegerField(BaseField):
     _type = int
@@ -32,14 +34,19 @@ class GeoField(BaseField):
     """
     A field to hold GeoPoint
 
-    self.mode = dict, array, string
+    mode = dict|array|string
+
+    >>> location = GeoField(mode='dict')  # default
+    An object representation with lat and lon explicitly named
+    >>> location = {"lat": 40.722, "lon": -73.989}}
+
+    >>> location = GeoField(mode='string')
+    A string representation, with "lat,lon"
+    >>> location = "40.715, -74.011"
 
-    string: A string representation, with "lat,lon"
-      {"location": "40.715, -74.011"}
-    array: An array representation with [lon,lat].
-      {"location": [ -73.983, 40.719 ]}
-    dict An object representation with lat and lon explicitly named.
-      { "location": { "lat": 40.722, "lon": -73.989}}
+    >>> location = GeoField(mode='array')
+    An array representation with [lon,lat].
+    >>> location = [-73.983, 40.719]
     """
 
     def __init__(self, *args, **kwargs):