Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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

Fix corresponding documentation and bump version number.
  • Loading branch information...
commit c054fd7017c96690b1e8430cc3a55ce1e6f99c2c 1 parent 781a5d3
Thomas Welfley authored
4 README.md
Source Rendered
@@ -102,12 +102,12 @@ QueryLists work just like lists:
102 102 True
103 103
104 104 They also let developers, exclude objects that don't match criteria via field
105   -lookups or limit the QueryList to only the objects that do match a provided
  105 +lookups or filter the QueryList to only the objects that do match a provided
106 106 criteria:
107 107
108 108 >>> ql.exclude(published=True)
109 109 [{'url': 'http://site3.tld/', 'meta': {'keywords': ['Mustard', 'kittens'], 'description': 'My cool site'}, 'id': 3, 'name': 'Site 3', 'published': False}]
110   - >>> ql.limit(published=True).exclude(meta__keywords__contains='Catsup')
  110 + >>> ql.filter(published=True).exclude(meta__keywords__contains='Catsup')
111 111 [{'url': 'http://site1.tld/', 'meta': {'keywords': ['Mustard', 'kittens'], 'description': 'My cool site'}, 'id': 1, 'name': 'Site 1', 'published': True}]
112 112
113 113 And finally, they let developers retrieve specific objects with the get
2  TODO.md
Source Rendered
... ... @@ -1,7 +1,7 @@
1 1 # Performance
2 2
3 3 * Performance can be improved dramatically by adopting a lazy evaluation
4   -approach. Instead of evaluating limiting/exclusion methods when they are
  4 +approach. Instead of evaluating filtering/exclusion methods when they are
5 5 called, those constraints can be passed on to output QueryLists and simply
6 6 accumulated.
7 7 * Instead of wrapping all elements with the wrapper on instantiation, that
7 docs/source/changelog.rst
Source Rendered
... ... @@ -1,6 +1,11 @@
1 1 Changelog
2 2 =========
3 3
  4 +**0.1.0**
  5 +
  6 +* Renamed QueryList's 'limit' method to 'filter' so that the QueryList API is
  7 + more consistent with Django's QuerySets.
  8 +
4 9 **0.0.1**
5 10
6   -* Initial relase
  11 +* Initial relase
29 docs/source/querylist.rst
Source Rendered
@@ -54,37 +54,37 @@ when the list was instantiated).
54 54 >>> a = QueryList(my_data)
55 55 >>> [item for item in a]
56 56
57   -Limiting and Excluding
58   -^^^^^^^^^^^^^^^^^^^^^^
  57 +Filtering and Excluding
  58 +^^^^^^^^^^^^^^^^^^^^^^^
59 59
60   -QueryLists provide two methods for limiting and excluding objects from a
61   -QueryList: ``limit()`` and ``exclude()``. ``limit()`` will return a QueryList
62   -containing all objects in the list that match the passed conditions, and
63   -``exclude()`` will return a QueryList containing the subset of the original
64   -QueryList that doesn't match the passed conditions.
  60 +QueryLists provide two methods for filtering and excluding objects from a
  61 +QueryList: ``filter()`` and ``exclude()``. ``filter()`` will return a
  62 +QueryList containing all objects in the list that match the passed conditions,
  63 +and ``exclude()`` will return a QueryList containing the subset of the
  64 +original QueryList that doesn't match the passed conditions.
65 65
66 66 Both methods accept keyword argument/value pairs, where the keyword is a field
67 67 lookup and the value is the value to compare that field to. For example,
68 68 ``id=4`` would match all objects with an id property equal to 4. See
69 69 :ref:`field_lookups` for more information.
70 70
71   -.. automethod:: querylist.QueryList.limit
  71 +.. automethod:: querylist.QueryList.filter
72 72 .. automethod:: querylist.QueryList.exclude
73 73
74 74 Chaining
75 75 ^^^^^^^^
76 76
77   -QueryList methods that return QueryLists (`limit()` and `exclude()`) can be
  77 +QueryList methods that return QueryLists (`filter()` and `exclude()`) can be
78 78 chained together to form more complex queries:
79 79
80   ->>> QueryList(sites).include(published=False).exclude(meta__keywords__contains="kittens")
  80 +>>> QueryList(sites).filter(published=False).exclude(meta__keywords__contains="kittens")
81 81 []
82 82
83 83 Retrieving a single object
84 84 ^^^^^^^^^^^^^^^^^^^^^^^^^^
85 85
86   -In addition to providing methods for limiting or excluding objects, QueryLists
87   -provide a method for retrieving specific objects:
  86 +In addition to providing methods for filtering or excluding objects,
  87 +QueryLists provide a method for retrieving specific objects:
88 88
89 89 .. automethod:: querylist.QueryList.get
90 90
@@ -218,8 +218,9 @@ Consider a user class that returns a list of sites::
218 218 """Returns a list of the user's sites."""
219 219 return Site(self.id).get_all_sites()
220 220
221   -If dictionaries are being used to represent sites, we can change the definition
222   -of ``get_sites()`` as follows without impacting any existing functionality::
  221 +If dictionaries are being used to represent sites, we can change the
  222 +definition of ``get_sites()`` as follows without impacting any existing
  223 +functionality::
223 224
224 225 def get_sites():
225 226 """Returns a list of the user's sites."""
2  querylist/__init__.py
@@ -3,7 +3,7 @@
3 3 from querylist import QueryList
4 4 from betterdict import BetterDict
5 5
6   -__version__ = "0.0.1"
  6 +__version__ = "0.1.0"
7 7 __author__ = "Thomas Welfley"
8 8
9 9 __all__ = ['QueryList', 'BetterDict']
14 querylist/querylist.py
@@ -68,11 +68,11 @@ def get(self, **kwargs):
68 68 {'url': 'http://site1.tld/', 'published': False, 'id': 1}
69 69 >>> site_list.get(published=True, id__lt=3)
70 70 {'url': 'http://site1.tld/', 'published': True, 'id': 2}
71   - >>> site_list.limit(published=True).get(id__lt=3)
  71 + >>> site_list.filter(published=True).get(id__lt=3)
72 72 {'url': 'http://site1.tld/', 'published': True, 'id': 2}
73 73
74 74 If the QueryList contains multiple elements that match the criteria,
75   - only the first match will be returned. Use ``limit()`` to retrieve
  75 + only the first match will be returned. Use ``filter()`` to retrieve
76 76 the entire set.
77 77
78 78 If no match is found in the QueryList, the method will raise a
@@ -120,27 +120,27 @@ def exclude(self, **kwargs):
120 120 data=(x for x in self if not self._check_element(kwargs, x)),
121 121 wrapper=self._wrapper, wrap=False)
122 122
123   - def limit(self, **kwargs):
  123 + def filter(self, **kwargs):
124 124 """Generates a QueryList containing the subset of objects from this
125 125 QueryList that match the provided set of field lookups.
126 126
127 127 The following example returns the subset of a QueryList named
128 128 ``site_list`` where published is equal to False:
129 129
130   - >>> site_list.limit(published=True)
  130 + >>> site_list.filter(published=True)
131 131 [{'url': 'http://site1.tld/',...}, {...}],
132 132
133   - Similarly, in the next example, ``limit()`` returns the subset of
  133 + Similarly, in the next example, ``filter()`` returns the subset of
134 134 objects where object.meta.keywords contains the string 'kittens' and
135 135 where the id property is greater than 100.
136 136
137   - >>> site_list.limit(meta__keywords__contains='kittens', id__gt=100)
  137 + >>> site_list.filter(meta__keywords__contains='kittens', id__gt=100)
138 138 [{'url': 'http://site101.tld/',...}, {...}],
139 139
140 140 If no objects match the provided field lookups, an empty QueryList
141 141 is returned.
142 142
143   - >>> site_list.limit(id__gte=1000, published=False)
  143 + >>> site_list.filter(id__gte=1000, published=False)
144 144 []
145 145
146 146 """
10 querylist/tests/querylist_tests.py
@@ -101,13 +101,13 @@ def test_returns_an_empty_querylist_if_all_items_match(self):
101 101 self.ql.exclude(meta__description__icontains='cool site'))
102 102
103 103
104   -class QueryListLimitMethodTests(QueryListMethodTests):
105   - """QueryList.limit()"""
  104 +class QueryListFilterMethodTests(QueryListMethodTests):
  105 + """QueryList.filter()"""
106 106 def test_returns_everything_if_it_is_passed_nothing(self):
107   - self.assertEqual(self.ql.limit(), self.src_list)
  107 + self.assertEqual(self.ql.filter(), self.src_list)
108 108
109 109 def test_returns_subset_of_matching_elements(self):
110   - self.assertEqual(self.ql.limit(published=False), [self.src_list[2]])
  110 + self.assertEqual(self.ql.filter(published=False), [self.src_list[2]])
111 111
112 112 def test_returns_an_empty_querylist_if_no_items_match(self):
113   - self.assertFalse(self.ql.limit(id=1000))
  113 + self.assertFalse(self.ql.filter(id=1000))

0 comments on commit c054fd7

Please sign in to comment.
Something went wrong with that request. Please try again.