Merge pull request ipython#209 from rmorshea/deprecate_class_traits

deprecate `class_traits` and `class_trait_names` + add event searchers

Author: minrk

traitlets/traitlets.py

@@ -1286,14 +1286,52 @@ def _register_validator(self, handler, names):
         for name in names:
             self._trait_validators[name] = handler
 
+    def add_traits(self, **traits):
+        """Dynamically add trait attributes to the HasTraits instance."""
+        self.__class__ = type(self.__class__.__name__, (self.__class__,),
+                              traits)
+        for trait in traits.values():
+            trait.instance_init(self)
+
+    def set_trait(self, name, value):
+        """Forcibly sets trait attribute, including read-only attributes."""
+        cls = self.__class__
+        if not self.has_trait(name):
+            raise TraitError("Class %s does not have a trait named %s" %
+                                (cls.__name__, name))
+        else:
+            getattr(cls, name).set(self, value)
+
+    @classmethod
+    def class_own_traits(cls, **metadata):
+        """Get a dict of all the traitlets defined on this class, not a parent.
+
+        Works like ``traits``, except for excluding traits from parents.
+        """
+        sup = super(cls, cls)
+        return {n: t for (n, t) in cls.traits(**metadata).items()
+                if getattr(sup, n, None) is not t}
+
+    @classmethod
+    def has_trait(cls, name):
+        """Returns True if the object has a trait with the specified name."""
+        return isinstance(getattr(cls, name, None), TraitType)
+
+    @classmethod
+    def trait_names(cls, **metadata):
+        """Get a list of all the names of this class' traits."""
+        return cls.traits(**metadata).keys()
+
     @classmethod
     def class_trait_names(cls, **metadata):
         """Get a list of all the names of this class' traits.
 
         This method is just like the :meth:`trait_names` method,
         but is unbound.
         """
-        return cls.class_traits(**metadata).keys()
+        warn("``HasTraits.class_trait_names`` is deprecated in favor of ``HasTraits.trait_names``"
+             " as a classmethod", DeprecationWarning, stacklevel=2)
+        return cls.traits(**metadata).keys()
 
     @classmethod
     def class_traits(cls, **metadata):
@@ -1312,43 +1350,12 @@ def class_traits(cls, **metadata):
         the output.  If a metadata key doesn't exist, None will be passed
         to the function.
         """
-        traits = dict([memb for memb in getmembers(cls) if
-                     isinstance(memb[1], TraitType)])
-
-        if len(metadata) == 0:
-            return traits
-
-        result = {}
-        for name, trait in traits.items():
-            for meta_name, meta_eval in metadata.items():
-                if type(meta_eval) is not types.FunctionType:
-                    meta_eval = _SimpleTest(meta_eval)
-                if not meta_eval(trait.metadata.get(meta_name, None)):
-                    break
-            else:
-                result[name] = trait
-
-        return result
+        warn("``HasTraits.class_traits`` is deprecated in favor of ``HasTraits.traits``"
+             " as a classmethod", DeprecationWarning, stacklevel=2)
+        return cls.traits(**metadata)
 
     @classmethod
-    def class_own_traits(cls, **metadata):
-        """Get a dict of all the traitlets defined on this class, not a parent.
-
-        Works like `class_traits`, except for excluding traits from parents.
-        """
-        sup = super(cls, cls)
-        return {n: t for (n, t) in cls.class_traits(**metadata).items()
-                if getattr(sup, n, None) is not t}
-
-    def has_trait(self, name):
-        """Returns True if the object has a trait with the specified name."""
-        return isinstance(getattr(self.__class__, name, None), TraitType)
-        
-    def trait_names(self, **metadata):
-        """Get a list of all the names of this class' traits."""
-        return self.traits(**metadata).keys()
-
-    def traits(self, **metadata):
+    def traits(cls, **metadata):
         """Get a ``dict`` of all the traits of this class.  The dictionary
         is keyed on the name and the values are the TraitType objects.
 
@@ -1362,49 +1369,71 @@ def traits(self, **metadata):
         the output.  If a metadata key doesn't exist, None will be passed
         to the function.
         """
-        traits = dict([memb for memb in getmembers(self.__class__) if
+        traits = dict([memb for memb in getmembers(cls) if
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
+        for meta_name, meta_eval in metadata.items():
+            if type(meta_eval) is not types.FunctionType:
+                metadata[meta_name] = _SimpleTest(meta_eval)
+
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
-                if type(meta_eval) is not types.FunctionType:
-                    meta_eval = _SimpleTest(meta_eval)
                 if not meta_eval(trait.metadata.get(meta_name, None)):
                     break
             else:
                 result[name] = trait
 
         return result
 
-    def trait_metadata(self, traitname, key, default=None):
+    @classmethod
+    def trait_metadata(cls, traitname, key, default=None):
         """Get metadata values for trait by key."""
         try:
-            trait = getattr(self.__class__, traitname)
+            trait = getattr(cls, traitname)
         except AttributeError:
             raise TraitError("Class %s does not have a trait named %s" %
-                                (self.__class__.__name__, traitname))
+                                (cls.__name__, traitname))
         else:
             return trait.metadata.get(key, default)
 
-    def add_traits(self, **traits):
-        """Dynamically add trait attributes to the HasTraits instance."""
-        self.__class__ = type(self.__class__.__name__, (self.__class__,),
-                              traits)
-        for trait in traits.values():
-            trait.instance_init(self)
+    @classmethod
+    def class_own_trait_events(cls, name):
+        """Get a dict of all event handlers defined on this class, not a parent.
 
-    def set_trait(self, name, value):
-        """Forcibly sets trait attribute, including read-only attributes."""
-        cls = self.__class__
-        if not self.has_trait(name):
-            raise TraitError("Class %s does not have a trait"
-                             "named %s" % (cls.__name__, name))
-        else:
-            getattr(cls, name).set(self, value)
+        Works like ``event_handlers``, except for excluding traits from parents.
+        """
+        sup = super(cls, cls)
+        return {n: e for (n, e) in cls.events(name).items()
+                if getattr(sup, n, None) is not e}
+
+    @classmethod
+    def trait_events(cls, name=None):
+        """Get a ``dict`` of all the event handlers of this class.
+
+        Parameters
+        ----------
+        name: str (default: None)
+            The name of a trait of this class. If name is ``None`` then all 
+            the event handlers of this class will be returned instead.
+
+        Returns
+        -------
+        The event handlers associated with a trait name, or all event handlers."""
+        events = {}
+        for k, v in getmembers(cls):
+            if isinstance(v, EventHandler):
+                if name is None:
+                    events[k] = v
+                elif name in v.trait_names:
+                    events[k] = v
+                elif hasattr(v, 'tags'):
+                    if cls.trait_names(**v.tags):
+                        events[k] = v
+        return events
 
 #-----------------------------------------------------------------------------
 # Actual TraitTypes implementations/subclasses