Barry Warsaw pushed to branch master at mailman / Mailman
Commits:
d6d598a1 by Barry Warsaw at 2016-03-16T21:48:04-04:00
Document the pagination API.
Closes #209
- - - - -
2 changed files:
- + src/mailman/rest/docs/collections.rst
- src/mailman/rest/docs/helpers.rst
Changes:
=====================================
src/mailman/rest/docs/collections.rst
=====================================
--- /dev/null
+++ b/src/mailman/rest/docs/collections.rst
@@ -0,0 +1,88 @@
+============================
+ Collections and Pagination
+============================
+
+All collections automatically support pagination. You can use this to limit
+the number of items of the collection that get returned, and you can page
+through the results by incrementing the page counter.
+
+For example, let's say we have 50 mailing lists.
+
+ >>> from mailman.app.lifecycle import create_list
+ >>> for i in range(50):
+ ... mlist = create_list('list{:02d}@example.com'.format(i))
+ >>> transaction.commit()
+
+We can get the first 10 lists by asking for the first page of items.
+
+ >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=1')
+ >>> for entry in json['entries']:
+ ... print(entry['list_id'])
+ list00.example.com
+ list01.example.com
+ list02.example.com
+ list03.example.com
+ list04.example.com
+ list05.example.com
+ list06.example.com
+ list07.example.com
+ list08.example.com
+ list09.example.com
+
+We can also ask for the third set of 10 mailing lists.
+
+ >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=3')
+ >>> for entry in json['entries']:
+ ... print(entry['list_id'])
+ list20.example.com
+ list21.example.com
+ list22.example.com
+ list23.example.com
+ list24.example.com
+ list25.example.com
+ list26.example.com
+ list27.example.com
+ list28.example.com
+ list29.example.com
+
+Of course, we can also adjust the page size and ask for the tenth page of 5
+mailing lists.
+
+ >>> json = call_http('http://localhost:9001/3.0/lists?count=5&page=10')
+ >>> for entry in json['entries']:
+ ... print(entry['list_id'])
+ list45.example.com
+ list46.example.com
+ list47.example.com
+ list48.example.com
+ list49.example.com
+
+
+The size of a collection
+========================
+
+This same idiom allows you to get just the size of the collection. You do
+this by asking for a page of size zero.
+
+ >>> dump_json('http://localhost:9001/3.0/lists?count=0&page=1')
+ http_etag: ...
+ start: 0
+ total_size: 50
+
+
+Page start
+==========
+
+Notice the `start` element in the returned JSON. This tells you which item of
+the collection the page starts on.
+
+ >>> dump_json('http://localhost:9001/3.0/lists?count=2&page=15')
+ entry 0:
+ display_name: List28
+ ...
+ entry 1:
+ display_name: List29
+ ...
+ http_etag: ...
+ start: 28
+ total_size: 50
=====================================
src/mailman/rest/docs/helpers.rst
=====================================
--- a/src/mailman/rest/docs/helpers.rst
+++ b/src/mailman/rest/docs/helpers.rst
@@ -121,7 +121,7 @@ But if the optional values are present, they must of course
also be valid.
Arrays
-------
+======
Some ``POST`` forms include more than one value for a particular key. This is
how lists and arrays are modeled. The validator does the right thing with
View it on GitLab:
https://gitlab.com/mailman/mailman/commit/d6d598a15d34b60fa4ceb3ee292bf2740addc878
_______________________________________________
Mailman-checkins mailing list
Mailman-checkins@python.org
Unsubscribe:
https://mail.python.org/mailman/options/mailman-checkins/archive%40jab.org
