Merge pull request #132 from enthought/document-fvalidate

Document fvalidate

docs/source/traits_user_manual/advanced.rst

@@ -1053,11 +1053,12 @@ The Property() function has the following signature:
 
 .. function:: Property( [fget=None, fset=None, fvalidate=None, force=False, handler=None, trait=None, **metadata] )
 
-All parameters are optional, including the *fget* "getter" and *fset* "setter"
-methods. If no parameters are specified, then the trait looks for and uses
-methods on the same class as the attribute that the trait is assigned to, with
-names of the form _get_\ *name*\ () and _set_\ *name*\ (), where *name* is the
-name of the trait attribute.
+All parameters are optional, including the *fget* "getter", *fvalidate*
+"validator"  and *fset* "setter" methods. If no parameters are specified, then
+the trait looks for and uses methods on the same class as the attribute that
+the trait is assigned to, with names of the form _get_\ *name*\ (), 
+_validate_\ *name*\ () and _set_\ *name*\ (), where *name* is the name of the 
+trait attribute.
 
 If you specify a trait as either the *fget* parameter or the *trait* parameter,
 that trait's handler supersedes the *handler* argument, if any. Because the

traits/traits.py

@@ -1015,7 +1015,8 @@ def Property ( fget = None, fset = None, fvalidate = None, force = False,
     fset : function
         The "setter" function for the property.
     fvalidate : function
-        The validation function for the property.
+        The validation function for the property. The method should return the
+        value to set or raise TraitError if the new value is not valid.
     force : bool
         Indicates whether to use only the function definitions specified by
         **fget** and **fset**, and not look elsewhere on the class.
@@ -1027,18 +1028,27 @@ def Property ( fget = None, fset = None, fvalidate = None, force = False,
 
     Description
     -----------
-    If no getter or setter functions are specified (and **force** is not True),
-    it is assumed that they are defined elsewhere on the class whose attribute
-    this trait is assigned to. For example::
+    If no getter, setter or validate functions are specified (and **force** is
+    not True), it is assumed that they are defined elsewhere on the class whose
+    attribute this trait is assigned to. For example::
 
         class Bar(HasTraits):
+            
+            # A float traits Property that should be always positive.
             foo = Property(Float)
+            
             # Shadow trait attribute
             _foo = Float
 
             def _set_foo(self,x):
                 self._foo = x
 
+            def _validate_foo(self, x):
+                if x <= 0:
+                    raise TraitError(
+                        'foo property should be a positive number')
+                return x
+
             def _get_foo(self):
                 return self._foo