diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/rest/docs/basic.txt | 9 | ||||
| -rw-r--r-- | src/mailman/rest/docs/configuration.txt | 20 | ||||
| -rw-r--r-- | src/mailman/rest/docs/domains.txt | 16 | ||||
| -rw-r--r-- | src/mailman/rest/docs/helpers.txt | 25 | ||||
| -rw-r--r-- | src/mailman/rest/docs/lists.txt | 10 | ||||
| -rw-r--r-- | src/mailman/rest/docs/membership.txt | 10 |
6 files changed, 60 insertions, 30 deletions
diff --git a/src/mailman/rest/docs/basic.txt b/src/mailman/rest/docs/basic.txt index 94d80e5a2..e5dab9ea8 100644 --- a/src/mailman/rest/docs/basic.txt +++ b/src/mailman/rest/docs/basic.txt @@ -2,7 +2,7 @@ REST server =========== -Mailman exposes a REST HTTP server for administrative control. +Mailman exposes a REST_ HTTP server for administrative control. The server listens for connections on a configurable host name and port. Because the REST server has full administrative access, it should always be @@ -22,10 +22,13 @@ returned. Non-existent links ================== -When you try to access an admin link that doesn't exist, you get the -appropriate HTTP 404 Not Found error. +When you try to access a link that doesn't exist, you get the appropriate HTTP +404 Not Found error. >>> dump_json('http://localhost:8001/3.0/does-not-exist') Traceback (most recent call last): ... HTTPError: HTTP Error 404: 404 Not Found + + +.. _REST: http://en.wikipedia.org/wiki/REST diff --git a/src/mailman/rest/docs/configuration.txt b/src/mailman/rest/docs/configuration.txt index 63f87fde1..dce9c8a95 100644 --- a/src/mailman/rest/docs/configuration.txt +++ b/src/mailman/rest/docs/configuration.txt @@ -63,8 +63,8 @@ Changing the full configuration =============================== Not all of the readable attributes can be set through the web interface. The -ones that can, can either be set via PUT or PATCH. PUT changes all the -writable attributes in one request. +ones that can, can either be set via ``PUT`` or ``PATCH``. ``PUT`` changes +all the writable attributes in one request. >>> dump_json('http://localhost:8001/3.0/lists/' ... 'test-one@example.com/config', @@ -132,8 +132,8 @@ These values are changed permanently. real_name: Fnords ... -If you use PUT to change a list's configuration, all writable attributes must -be included. It is an error to leave one or more out... +If you use ``PUT`` to change a list's configuration, all writable attributes +must be included. It is an error to leave one or more out... >>> dump_json('http://localhost:8001/3.0/lists/' ... 'test-one@example.com/config', @@ -301,7 +301,7 @@ It is also an error to spell an attribute value incorrectly... Changing a partial configuration ================================ -Using PATCH, you can change just one attribute. +Using ``PATCH``, you can change just one attribute. >>> dump_json('http://localhost:8001/3.0/lists/' ... 'test-one@example.com/config', @@ -330,9 +330,9 @@ retrieved and set through the sub-resource. Acceptable aliases ------------------ -These are recipient aliases that can be used in the To and CC headers instead -of the posting address. They are often used in forwarded emails. By default, -a mailing list has no acceptable aliases. +These are recipient aliases that can be used in the ``To:`` and ``CC:`` +headers instead of the posting address. They are often used in forwarded +emails. By default, a mailing list has no acceptable aliases. >>> from mailman.interfaces.mailinglist import IAcceptableAliasSet >>> IAcceptableAliasSet(mlist).clear() @@ -342,7 +342,7 @@ a mailing list has no acceptable aliases. acceptable_aliases: [] http_etag: "..." -We can add a few by PUTting them on the sub-resource. The keys in the +We can add a few by ``PUT``-ing them on the sub-resource. The keys in the dictionary are ignored. >>> dump_json('http://localhost:8001/3.0/lists/' @@ -355,7 +355,7 @@ dictionary are ignored. server: WSGIServer/... status: 200 -Aliases are returned as a list on the 'aliases' key. +Aliases are returned as a list on the ``aliases`` key. >>> response = call_http( ... 'http://localhost:8001/3.0/lists/' diff --git a/src/mailman/rest/docs/domains.txt b/src/mailman/rest/docs/domains.txt index a3a6f1227..b9b7dc3d6 100644 --- a/src/mailman/rest/docs/domains.txt +++ b/src/mailman/rest/docs/domains.txt @@ -2,6 +2,9 @@ Domains ======= +`Domains`_ are how Mailman interacts with email host names and web host names. +:: + # The test framework starts out with an example domain, so let's delete # that first. >>> from mailman.interfaces.domain import IDomainManager @@ -20,7 +23,8 @@ initially none. start: 0 total_size: 0 -Once a domain is added though, it is accessible through the API. +Once a domain is added, it is accessible through the API. +:: >>> domain_manager.add( ... 'example.com', 'An example domain', 'http://lists.example.com') @@ -43,6 +47,7 @@ Once a domain is added though, it is accessible through the API. total_size: 1 At the top level, all domains are returned as separate entries. +:: >>> domain_manager.add( ... 'example.org', @@ -94,7 +99,7 @@ Individual domains ================== The information for a single domain is available by following one of the -self_links from the above collection. +``self_links`` from the above collection. >>> dump_json('http://localhost:8001/3.0/domains/lists.example.net') base_url: http://example.net @@ -116,7 +121,7 @@ But we get a 404 for a non-existent domain. Creating new domains ==================== -New domains can be created by posting to the 'domains' url. +New domains can be created by posting to the ``domains`` url. >>> dump_json('http://localhost:8001/3.0/domains', { ... 'email_host': 'lists.example.com', @@ -138,6 +143,7 @@ Now the web service knows about our new domain. url_host: lists.example.com And the new domain is in our database. +:: >>> domain_manager['lists.example.com'] <Domain lists.example.com, @@ -149,6 +155,7 @@ And the new domain is in our database. You can also create a new domain with a description, a base url, and a contact address. +:: >>> dump_json('http://localhost:8001/3.0/domains', { ... 'email_host': 'my.example.com', @@ -177,3 +184,6 @@ address. # Unlock the database. >>> transaction.abort() + + +.. _Domains: ../../model/docs/domains.html diff --git a/src/mailman/rest/docs/helpers.txt b/src/mailman/rest/docs/helpers.txt index a47d67fa8..eec72da84 100644 --- a/src/mailman/rest/docs/helpers.txt +++ b/src/mailman/rest/docs/helpers.txt @@ -16,8 +16,9 @@ function can return them the full path to the resource. >>> print path_to('system') http://localhost:8001/3.0/system -Parameters like the scheme, host, port, and API version number can be set in -the configuration file. +Parameters like the ``scheme``, ``host``, ``port``, and API version number can +be set in the configuration file. +:: >>> config.push('helpers', """ ... [webservice] @@ -34,10 +35,10 @@ the configuration file. Etags ===== -HTTP etags are a way for clients to decide whether their copy of a resource +HTTP *etags* are a way for clients to decide whether their copy of a resource has changed or not. Mailman's REST API calculates this in a cheap and dirty way. Pass in the dictionary representing the resource and that dictionary -gets modified to contain the etag under the `http_etag` key. +gets modified to contain the etag under the ``http_etag`` key. >>> from mailman.rest.helpers import etag >>> resource = dict(geddy='bass', alex='guitar', neil='drums') @@ -47,6 +48,7 @@ gets modified to contain the etag under the `http_etag` key. For convenience, the etag function also returns the JSON representation of the dictionary after tagging, since that's almost always what you want. +:: >>> import json >>> data = json.loads(json_data) @@ -62,8 +64,9 @@ dictionary after tagging, since that's almost always what you want. POST unpacking ============== -Another helper unpacks POST request variables, validating and converting their -values. +Another helper unpacks ``POST`` request variables, validating and converting +their values. +:: >>> from mailman.rest.validator import Validator >>> validator = Validator(one=int, two=unicode, three=bool) @@ -113,6 +116,7 @@ Extra keys are also not allowed. ValueError: Unexpected parameters: five, four However, if optional keys are missing, it's okay. +:: >>> validator = Validator(one=int, two=unicode, three=bool, ... four=int, five=int, @@ -146,10 +150,11 @@ 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 such -form data. Specifically, when a key shows up multiple times in the form data, -a list is given to the validator. +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 +such form data. Specifically, when a key shows up multiple times in the form +data, a list is given to the validator. +:: # Of course we can't use a normal dictionary, but webob has a useful data # type we can use. diff --git a/src/mailman/rest/docs/lists.txt b/src/mailman/rest/docs/lists.txt index 3cb7e1481..4cb00e378 100644 --- a/src/mailman/rest/docs/lists.txt +++ b/src/mailman/rest/docs/lists.txt @@ -12,6 +12,7 @@ yet though. total_size: 0 Create a mailing list in a domain and it's accessible via the API. +:: >>> create_list('test-one@example.com') <mailing list "test-one@example.com" at ...> @@ -34,7 +35,7 @@ Creating lists via the API ========================== New mailing lists can also be created through the API, by posting to the -'lists' URL. +``lists`` URL. >>> dump_json('http://localhost:8001/3.0/lists', { ... 'fqdn_listname': 'test-two@example.com', @@ -45,6 +46,7 @@ New mailing lists can also be created through the API, by posting to the ... The mailing list exists in the database. +:: >>> from mailman.interfaces.listmanager import IListManager >>> from zope.component import getUtility @@ -90,8 +92,9 @@ Nor can you create a mailing list that already exists. Deleting lists via the API ========================== -Existing mailing lists can be deleted through the API, by doing an HTTP DELETE -on the mailing list URL. +Existing mailing lists can be deleted through the API, by doing an HTTP +``DELETE`` on the mailing list URL. +:: >>> dump_json('http://localhost:8001/3.0/lists/test-two@example.com', ... method='DELETE') @@ -111,6 +114,7 @@ The mailing list does not exist. You cannot delete a mailing list that does not exist or has already been deleted. +:: >>> dump_json('http://localhost:8001/3.0/lists/test-two@example.com', ... method='DELETE') diff --git a/src/mailman/rest/docs/membership.txt b/src/mailman/rest/docs/membership.txt index 0b5eb063a..d34794447 100644 --- a/src/mailman/rest/docs/membership.txt +++ b/src/mailman/rest/docs/membership.txt @@ -3,7 +3,7 @@ Membership ========== The REST API can be used to subscribe and unsubscribe users to mailing lists. -A subscribed user is called a 'member'. There is a top level collection that +A subscribed user is called a *member*. There is a top level collection that returns all the members of all known mailing lists. There are no mailing lists and no members yet. @@ -14,6 +14,7 @@ There are no mailing lists and no members yet. total_size: 0 We create a mailing list, which starts out with no members. +:: >>> mlist_one = create_list('test-one@example.com') >>> transaction.commit() @@ -29,6 +30,7 @@ Subscribers After Bart subscribes to the mailing list, his subscription is available via the REST interface. +:: >>> from mailman.interfaces.member import MemberRole >>> from mailman.interfaces.usermanager import IUserManager @@ -62,6 +64,7 @@ the REST interface. The subscribed members are returned in alphabetical order, so when Anna subscribes, she is returned first. +:: >>> subscribe(mlist_one, 'Anna') @@ -81,6 +84,7 @@ subscribes, she is returned first. Subscriptions are also returned alphabetically by mailing list posting address. Anna and Cris subscribe to this new mailing list. +:: >>> mlist_two = create_list('alpha@example.com') >>> subscribe(mlist_two, 'Anna') @@ -127,6 +131,7 @@ Owners and moderators Mailing list owners and moderators also show up in the REST API. Cris becomes an owner of the alpha mailing list and Dave becomes a moderator of the test-one mailing list. +:: >>> subscribe(mlist_one, 'Cris', MemberRole.owner) >>> subscribe(mlist_two, 'Dave', MemberRole.moderator) @@ -180,6 +185,7 @@ created for her. ... Elly is now a member of the mailing list. +:: >>> elly = user_manager.get_user('eperson@example.com') >>> elly @@ -202,6 +208,7 @@ Leaving a mailing list Elly decides she does not want to be a member of the mailing list after all, so she leaves from the mailing list. +:: # Ensure our previous reads don't keep the database lock. >>> transaction.abort() @@ -222,6 +229,7 @@ Digest delivery =============== Fred joins the alpha mailing list but wants MIME digest delivery. +:: >>> transaction.abort() >>> dump_json('http://localhost:8001/3.0/members', { |