Permalink
Browse files

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

Fix corresponding documentation and bump version number.
  • Loading branch information...
1 parent 781a5d3 commit c054fd7017c96690b1e8430cc3a55ce1e6f99c2c @thomasw committed Dec 16, 2012
Showing with 37 additions and 31 deletions.
  1. +2 −2 README.md
  2. +1 −1 TODO.md
  3. +6 −1 docs/source/changelog.rst
  4. +15 −14 docs/source/querylist.rst
  5. +1 −1 querylist/__init__.py
  6. +7 −7 querylist/querylist.py
  7. +5 −5 querylist/tests/querylist_tests.py
View
@@ -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
View
@@ -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
@@ -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
@@ -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."""
@@ -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']
@@ -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)
[]
"""
@@ -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))

0 comments on commit c054fd7

Please sign in to comment.