Merge pull request #78 from sseyler/develop

`AggTags` now has `filter()` method + unit tests

Closes #53

src/datreant/core/agglimbs.py

@@ -243,7 +243,7 @@ def fuzzy(self, tag, threshold=80, scope='all'):
 
         Parameters
         ----------
-        tags : str or list
+        tag : str or list
             Tag or tags to get fuzzy matches for.
         threshold : int
             Lowest match score to return. Setting to 0 will return every tag,
@@ -278,6 +278,22 @@ def fuzzy(self, tag, threshold=80, scope='all'):
 
         return tuple(matches)
 
+    def filter(self, tag):
+        """Filter Treants matching the given tag expression from a Bundle.
+
+        Parameters
+        ----------
+        tag : str or list
+            Tag or tags to filter Treants.
+
+        Returns
+        -------
+        Bundle
+            Bundle of Treants matching the given tag expression.
+        """
+        matches = self._collection.tags[tag]
+        return self._collection[matches]
+
 
 class AggCategories(AggLimb):
     """Interface to categories.

src/datreant/core/tests/test_collections.py

@@ -378,6 +378,64 @@ def test_tags_getitem(self, collection, testtreant, testgroup, tmpdir):
         def test_tags_fuzzy(self, collection, testtreant, testgroup, tmpdir):
             pass
 
+        def test_tags_filter(self, collection, testtreant, testgroup, tmpdir):
+            with tmpdir.as_cwd():
+
+                maple = dtr.Treant('maple')
+                pine = dtr.Treant('pine')
+                maple.tags.add({'tree', 'new jersey', 'deciduous'})
+                pine.tags.add({'tree', 'new york', 'evergreen'})
+                collection.add(maple, pine)
+                tags = collection.tags
+
+                maple_bund = dtr.Bundle(maple)
+                pine_bund = dtr.Bundle(pine)
+
+                assert len(tags.any) == 5
+
+                # filter using single tags
+                assert tags.filter('tree') == collection
+                assert tags.filter({'tree'}) == dtr.Bundle()
+                assert tags.filter('deciduous') == maple_bund
+                assert tags.filter('evergreen') == pine_bund
+                assert tags.filter('new jersey') == maple_bund
+                assert tags.filter('new york') == pine_bund
+
+                # filter Treants that DON'T have a given tag
+                assert tags.filter({'new york'}) == maple_bund
+                assert tags.filter({'deciduous'}) == pine_bund
+
+                # filter Treants containing all of the tags
+                assert tags.filter(['deciduous', 'tree']) == maple_bund
+                assert tags.filter(['evergreen', 'tree']) == pine_bund
+                assert tags.filter(['deciduous', 'new york']) == dtr.Bundle()
+
+                # filter Treants containing any of the tags tags
+                assert tags.filter(('evergreen', 'tree')) == collection
+                assert tags.filter(('deciduous', 'new york')) == collection
+                assert tags.filter(('evergreen', 'new york')) == pine_bund
+
+                # filter Treants that exclude any of the provided tags
+                assert tags.filter({'deciduous', 'new york'}) == collection
+                assert tags.filter({'deciduous', 'new jersey'}) == pine_bund
+                assert tags.filter({'evergreen', 'tree'}) == maple_bund
+
+                # complex logic tests
+
+                # give those that are evergreen or in NY AND also not deciduous
+                selection = [('evergreen', 'new york'), {'deciduous'}]
+                assert tags.filter(selection) == pine_bund
+                # give those that are evergreen or in NY AND also not a tree
+                selection = [('evergreen', 'new york'), {'tree'}]
+                assert tags.filter(selection) == dtr.Bundle()
+                # give a tree that's in NJ OR anything that's not evergreen
+                selection = (['tree', 'new jersey'], {'evergreen'})
+                assert tags.filter(selection) == maple_bund
+                # cannot be a tree in NJ, AND must also be deciduous
+                # I.e., give all deciduous things that aren't trees in NJ
+                selection = [{'tree', 'new jersey'}, 'deciduous']
+                assert tags.filter(selection) == dtr.Bundle()
+
     class TestAggCategories:
         """Test behavior of manipulating categories collectively.