Rename QueryList.limit() to QueryList.filter()

Fix corresponding documentation and bump version number.

README.md

@@ -102,12 +102,12 @@ QueryLists work just like lists:
     True
 
 They also let developers, exclude objects that don't match criteria via field
-lookups or limit the QueryList to only the objects that do match a provided
+lookups or filter the QueryList to only the objects that do match a provided
 criteria:
 
     >>> ql.exclude(published=True)
     [{'url': 'http://site3.tld/', 'meta': {'keywords': ['Mustard', 'kittens'], 'description': 'My cool site'}, 'id': 3, 'name': 'Site 3', 'published': False}]
-    >>> ql.limit(published=True).exclude(meta__keywords__contains='Catsup')
+    >>> ql.filter(published=True).exclude(meta__keywords__contains='Catsup')
     [{'url': 'http://site1.tld/', 'meta': {'keywords': ['Mustard', 'kittens'], 'description': 'My cool site'}, 'id': 1, 'name': 'Site 1', 'published': True}]
 
 And finally, they let developers retrieve specific objects with the get

TODO.md

@@ -1,7 +1,7 @@
 # Performance
 
 * Performance can be improved dramatically by adopting a lazy evaluation
-approach. Instead of evaluating limiting/exclusion methods when they are
+approach. Instead of evaluating filtering/exclusion methods when they are
 called, those constraints can be passed on to output QueryLists and simply
 accumulated.
 * Instead of wrapping all elements with the wrapper on instantiation, that

docs/source/changelog.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+**0.1.0**
+
+* Renamed QueryList's 'limit' method to 'filter' so that the QueryList API is
+  more consistent with Django's QuerySets.
+
 **0.0.1**
 
-* Initial relase
+* Initial relase

docs/source/querylist.rst

@@ -54,37 +54,37 @@ when the list was instantiated).
 >>> a = QueryList(my_data)
 >>> [item for item in a]
 
-Limiting and Excluding
-^^^^^^^^^^^^^^^^^^^^^^
+Filtering and Excluding
+^^^^^^^^^^^^^^^^^^^^^^^
 
-QueryLists provide two methods for limiting and excluding objects from a
-QueryList: ``limit()`` and ``exclude()``. ``limit()`` will return a QueryList
-containing all objects in the list that match the passed conditions, and
-``exclude()`` will return a QueryList containing the subset of the original
-QueryList that doesn't match the passed conditions.
+QueryLists provide two methods for filtering and excluding objects from a
+QueryList: ``filter()`` and ``exclude()``. ``filter()`` will return a
+QueryList containing all objects in the list that match the passed conditions,
+and ``exclude()`` will return a QueryList containing the subset of the
+original QueryList that doesn't match the passed conditions.
 
 Both methods accept keyword argument/value pairs, where the keyword is a field
 lookup and the value is the value to compare that field to. For example,
 ``id=4`` would match all objects with an id property equal to 4. See
 :ref:`field_lookups` for more information.
 
-.. automethod:: querylist.QueryList.limit
+.. automethod:: querylist.QueryList.filter
 .. automethod:: querylist.QueryList.exclude
 
 Chaining
 ^^^^^^^^
 
-QueryList methods that return QueryLists  (`limit()` and `exclude()`) can be
+QueryList methods that return QueryLists  (`filter()` and `exclude()`) can be
 chained together to form more complex queries:
 
->>> QueryList(sites).include(published=False).exclude(meta__keywords__contains="kittens")
+>>> QueryList(sites).filter(published=False).exclude(meta__keywords__contains="kittens")
 []
 
 Retrieving a single object
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to providing methods for limiting or excluding objects, QueryLists
-provide a method for retrieving specific objects:
+In addition to providing methods for filtering or excluding objects,
+QueryLists provide a method for retrieving specific objects:
 
 .. automethod:: querylist.QueryList.get
 
@@ -218,8 +218,9 @@ Consider a user class that returns a list of sites::
             """Returns a list of the user's sites."""
             return Site(self.id).get_all_sites()
 
-If dictionaries are being used to represent sites, we can change the definition
-of ``get_sites()`` as follows without impacting any existing functionality::
+If dictionaries are being used to represent sites, we can change the
+definition of ``get_sites()`` as follows without impacting any existing
+functionality::
 
     def get_sites():
         """Returns a list of the user's sites."""

querylist/__init__.py

@@ -3,7 +3,7 @@
 from querylist import QueryList
 from betterdict import BetterDict
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"
 __author__ = "Thomas Welfley"
 
 __all__ = ['QueryList', 'BetterDict']

querylist/querylist.py

@@ -68,11 +68,11 @@ def get(self, **kwargs):
         {'url': 'http://site1.tld/', 'published': False, 'id': 1}
         >>> site_list.get(published=True, id__lt=3)
         {'url': 'http://site1.tld/', 'published': True, 'id': 2}
-        >>> site_list.limit(published=True).get(id__lt=3)
+        >>> site_list.filter(published=True).get(id__lt=3)
         {'url': 'http://site1.tld/', 'published': True, 'id': 2}
 
         If the QueryList contains multiple elements that match the criteria,
-        only the first match will be returned. Use ``limit()`` to retrieve
+        only the first match will be returned. Use ``filter()`` to retrieve
         the entire set.
 
         If no match is found in the QueryList, the method will raise a
@@ -120,27 +120,27 @@ def exclude(self, **kwargs):
             data=(x for x in self if not self._check_element(kwargs, x)),
             wrapper=self._wrapper, wrap=False)
 
-    def limit(self, **kwargs):
+    def filter(self, **kwargs):
         """Generates a QueryList containing the subset of objects from this
         QueryList that match the provided set of field lookups.
 
         The following example returns the subset of a QueryList named
         ``site_list`` where published is equal to False:
 
-        >>> site_list.limit(published=True)
+        >>> site_list.filter(published=True)
         [{'url': 'http://site1.tld/',...}, {...}],
 
-        Similarly, in the next example, ``limit()`` returns the subset of
+        Similarly, in the next example, ``filter()`` returns the subset of
         objects where object.meta.keywords contains the string 'kittens' and
         where the id property is greater than 100.
 
-        >>> site_list.limit(meta__keywords__contains='kittens', id__gt=100)
+        >>> site_list.filter(meta__keywords__contains='kittens', id__gt=100)
         [{'url': 'http://site101.tld/',...}, {...}],
 
         If no objects match the provided field lookups, an empty QueryList
         is returned.
 
-        >>> site_list.limit(id__gte=1000, published=False)
+        >>> site_list.filter(id__gte=1000, published=False)
         []
 
         """

querylist/tests/querylist_tests.py

@@ -101,13 +101,13 @@ def test_returns_an_empty_querylist_if_all_items_match(self):
             self.ql.exclude(meta__description__icontains='cool site'))
 
 
-class QueryListLimitMethodTests(QueryListMethodTests):
-    """QueryList.limit()"""
+class QueryListFilterMethodTests(QueryListMethodTests):
+    """QueryList.filter()"""
     def test_returns_everything_if_it_is_passed_nothing(self):
-        self.assertEqual(self.ql.limit(), self.src_list)
+        self.assertEqual(self.ql.filter(), self.src_list)
 
     def test_returns_subset_of_matching_elements(self):
-        self.assertEqual(self.ql.limit(published=False), [self.src_list[2]])
+        self.assertEqual(self.ql.filter(published=False), [self.src_list[2]])
 
     def test_returns_an_empty_querylist_if_no_items_match(self):
-        self.assertFalse(self.ql.limit(id=1000))
+        self.assertFalse(self.ql.filter(id=1000))