diff options
36 files changed, 240 insertions, 146 deletions
diff --git a/src/mailman/app/docs/bounces.txt b/src/mailman/app/docs/bounces.txt index a12305154..3d21ee423 100644 --- a/src/mailman/app/docs/bounces.txt +++ b/src/mailman/app/docs/bounces.txt @@ -28,7 +28,7 @@ Any message can be bounced. Bounce a message by passing in the original message, and an optional error message. The bounced message ends up in the virgin queue, awaiting sending -to the original messageauthor. +to the original message author. >>> from mailman.app.bounces import bounce_message >>> bounce_message(mlist, msg) @@ -66,7 +66,7 @@ to the original messageauthor. An error message can be given when the message is bounced, and this will be included in the payload of the text/plain part. The error message must be -passed in as an instance of a RejectMessage exception. +passed in as an instance of a ``RejectMessage`` exception. >>> from mailman.core.errors import RejectMessage >>> error = RejectMessage("This wasn't very important after all.") diff --git a/src/mailman/app/docs/chains.txt b/src/mailman/app/docs/chains.txt index 216bf2f5b..18cd61443 100644 --- a/src/mailman/app/docs/chains.txt +++ b/src/mailman/app/docs/chains.txt @@ -13,7 +13,8 @@ processing of messages. The Discard chain ================= -The Discard chain simply throws the message away. +The `discard` chain simply throws the message away. +:: >>> from zope.interface.verify import verifyObject >>> from mailman.interfaces.chain import IChain @@ -50,8 +51,9 @@ The Discard chain simply throws the message away. The Reject chain ================ -The Reject chain bounces the message back to the original sender, and logs +The `reject` chain bounces the message back to the original sender, and logs this action. +:: >>> chain = config.chains['reject'] >>> verifyObject(IChain, chain) @@ -65,7 +67,7 @@ this action. ... process(mlist, msg, {}, 'reject') REJECT: <first> -The bounce message is now sitting in the Virgin queue. +The bounce message is now sitting in the `virgin` queue. >>> from mailman.testing.helpers import get_queue_messages >>> qfiles = get_queue_messages('virgin') @@ -94,9 +96,10 @@ The bounce message is now sitting in the Virgin queue. The Hold Chain ============== -The Hold chain places the message into the admin request database and +The `hold` chain places the message into the admin request database and depending on the list's settings, sends a notification to both the original sender and the list moderators. +:: >>> chain = config.chains['hold'] >>> verifyObject(IChain, chain) @@ -203,6 +206,7 @@ for them to be disposed of by the original author or the list moderators. The database is essentially a dictionary, with the keys being the randomly selected tokens included in the urls and the values being a 2-tuple where the first item is a type code and the second item is a message id. +:: >>> import re >>> cookie = None @@ -221,6 +225,7 @@ first item is a type code and the second item is a message id. [(u'id', ...), (u'type', u'held message')] The message itself is held in the message store. +:: >>> from mailman.interfaces.requests import IRequests >>> list_requests = getUtility(IRequests).get_list_requests(mlist) @@ -245,7 +250,7 @@ The message itself is held in the message store. The Accept chain ================ -The Accept chain sends the message on the 'prep' queue, where it will be +The `accept` chain sends the message on the `pipeline` queue, where it will be processed and sent on to the list membership. >>> chain = config.chains['accept'] @@ -278,10 +283,10 @@ Run-time chains We can also define chains at run time, and these chains can be mutated. Run-time chains are made up of links where each link associates both a rule -and a 'jump'. The rule is really a rule name, which is looked up when +and a `jump`. The rule is really a rule name, which is looked up when needed. The jump names a chain which is jumped to if the rule matches. -There is one built-in run-time chain, called appropriately 'built-in'. This +There is one built-in run-time chain, called appropriately `built-in`. This is the default chain to use when no other input chain is defined for a mailing list. It runs through the default rules, providing functionality similar to the Hold handler from previous versions of Mailman. @@ -295,7 +300,8 @@ the Hold handler from previous versions of Mailman. The built-in moderation chain. The previously created message is innocuous enough that it should pass through -all default rules. This message will end up in the pipeline queue. +all default rules. This message will end up in the `pipeline` queue. +:: >>> with event_subscribers(print_msgid): ... process(mlist, msg, {}) diff --git a/src/mailman/app/docs/hooks.txt b/src/mailman/app/docs/hooks.txt index efd5530f5..7e214f13f 100644 --- a/src/mailman/app/docs/hooks.txt +++ b/src/mailman/app/docs/hooks.txt @@ -4,7 +4,8 @@ Hooks Mailman defines two initialization hooks, one which is run early in the initialization process and the other run late in the initialization process. -Hooks name an importable callable so it must be accessible on sys.path. +Hooks name an importable callable so it must be accessible on ``sys.path``. +:: >>> import os, sys >>> from mailman.config import config @@ -46,6 +47,7 @@ We can set the pre-hook in the configuration file. The hooks are run in the second and third steps of initialization. However, we can't run those initialization steps in process, so call a command line script that will produce no output to force the hooks to run. +:: >>> import subprocess >>> from mailman.testing.layers import ConfigLayer @@ -71,6 +73,7 @@ Post-hook ========= We can set the post-hook in the configuration file. +:: >>> with open(config_path, 'w') as fp: ... print >> fp, """\ @@ -92,6 +95,7 @@ Running both hooks ================== We can set the pre- and post-hooks in the configuration file. +:: >>> with open(config_path, 'w') as fp: ... print >> fp, """\ diff --git a/src/mailman/app/docs/lifecycle.txt b/src/mailman/app/docs/lifecycle.txt index 959c08cc8..43ba1f565 100644 --- a/src/mailman/app/docs/lifecycle.txt +++ b/src/mailman/app/docs/lifecycle.txt @@ -3,8 +3,8 @@ Application level list life cycle ================================= The low-level way to create and delete a mailing list is to use the -IListManager interface. This interface simply adds or removes the appropriate -database entries to record the list's creation. +``IListManager`` interface. This interface simply adds or removes the +appropriate database entries to record the list's creation. There is a higher level interface for creating and deleting mailing lists which performs additional tasks such as: @@ -17,8 +17,6 @@ which performs additional tasks such as: * notifying watchers of list creation; * creating ancillary artifacts (such as the list's on-disk directory) - >>> from mailman.app.lifecycle import create_list - Posting address validation ========================== @@ -44,6 +42,7 @@ Creating a list applies its styles ================================== Start by registering a test style. +:: >>> from zope.interface import implements >>> from mailman.interfaces.styles import IStyle @@ -102,6 +101,7 @@ However, all addresses are linked to users. If you create a mailing list with owner addresses that are already known to the system, they won't be created again. +:: >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility @@ -126,6 +126,7 @@ Deleting a list Removing a mailing list deletes the list, all its subscribers, and any related artifacts. +:: >>> from mailman.app.lifecycle import remove_list >>> remove_list(mlist_2.fqdn_listname, mlist_2, True) diff --git a/src/mailman/app/docs/message.txt b/src/mailman/app/docs/message.txt index 41607ff44..3e3293196 100644 --- a/src/mailman/app/docs/message.txt +++ b/src/mailman/app/docs/message.txt @@ -3,19 +3,19 @@ Messages ======== Mailman has its own Message classes, derived from the standard -email.message.Message class, but providing additional useful methods. +``email.message.Message`` class, but providing additional useful methods. User notifications ================== -When Mailman needs to send a message to a user, it creates a UserNotification -instance, and then calls the .send() method on this object. This method -requires a mailing list instance. +When Mailman needs to send a message to a user, it creates a +``UserNotification`` instance, and then calls the ``.send()`` method on this +object. This method requires a mailing list instance. >>> mlist = create_list('_xtest@example.com') -The UserNotification constructor takes the recipient address, the sender +The ``UserNotification`` constructor takes the recipient address, the sender address, an optional subject, optional body text, and optional language. >>> from mailman.email.message import UserNotification @@ -26,7 +26,7 @@ address, an optional subject, optional body text, and optional language. ... 'I needed to tell you this.') >>> msg.send(mlist) -The message will end up in the virgin queue. +The message will end up in the `virgin` queue. >>> switchboard = config.switchboards['virgin'] >>> len(switchboard.files) diff --git a/src/mailman/app/docs/styles.txt b/src/mailman/app/docs/styles.txt index 10312cd3a..63ec999bf 100644 --- a/src/mailman/app/docs/styles.txt +++ b/src/mailman/app/docs/styles.txt @@ -13,6 +13,7 @@ or not. And finally, application of a style to a mailing list can really modify the mailing list any way it wants. Let's start with a vanilla mailing list and a default style manager. +:: >>> from mailman.interfaces.listmanager import IListManager >>> from zope.component import getUtility @@ -44,9 +45,9 @@ last. Given a mailing list, you can ask the style manager to find all the styles that match the list. The registered styles will be sorted by decreasing -priority and each style's `match()` method will be called in turn. The sorted -list of matching styles will be returned -- but not applied -- by the style -manager's `lookup()` method. +priority and each style's ``match()`` method will be called in turn. The +sorted list of matching styles will be returned -- but not applied -- by the +style manager's ``lookup()`` method. >>> [style.name for style in style_manager.lookup(mlist)] ['default'] @@ -55,7 +56,7 @@ manager's `lookup()` method. Registering styles ================== -New styles must implement the IStyle interface. +New styles must implement the ``IStyle`` interface. >>> from zope.interface import implements >>> from mailman.interfaces.styles import IStyle @@ -93,6 +94,7 @@ Style priority When multiple styles match a particular mailing list, they are applied in descending order of priority. In other words, a priority zero style would be applied last. +:: >>> class AnotherTestStyle(TestStyle): ... name = 'another' diff --git a/src/mailman/app/docs/system.txt b/src/mailman/app/docs/system.txt index 035833047..844db9ee6 100644 --- a/src/mailman/app/docs/system.txt +++ b/src/mailman/app/docs/system.txt @@ -2,8 +2,9 @@ System versions =============== -Mailman system information is available through the System object, which -implements the ISystem interface. +Mailman system information is available through the ``system`` object, which +implements the ``ISystem`` interface. +:: >>> from mailman.interfaces.system import ISystem >>> from mailman.core.system import system @@ -12,13 +13,14 @@ implements the ISystem interface. >>> verifyObject(ISystem, system) True -The Mailman version is available via the system object. +The Mailman version is also available via the ``system`` object. >>> print system.mailman_version GNU Mailman ... -The Python version running underneath is also available via the system +The Python version running underneath is also available via the ``system`` object. +:: # The entire python_version string is variable, so this is the best test # we can do. diff --git a/src/mailman/bin/docs/master.txt b/src/mailman/bin/docs/master.txt index 20eddae2c..d3c07c768 100644 --- a/src/mailman/bin/docs/master.txt +++ b/src/mailman/bin/docs/master.txt @@ -3,9 +3,9 @@ Mailman queue runner control ============================ Mailman has a number of queue runners which process messages in its queue file -directories. In normal operation, the 'bin/mailman' command is used to start, -stop and manage the queue runners. This is just a wrapper around the real -queue runner watcher script called master.py. +directories. In normal operation, the ``bin/mailman`` command is used to +start, stop and manage the queue runners. This is just a wrapper around the +real queue runner watcher script called master.py. >>> from mailman.testing.helpers import TestableMaster @@ -23,6 +23,7 @@ There should be a process id for every qrunner that claims to be startable. True Now verify that all the qrunners are running. +:: >>> import os diff --git a/src/mailman/commands/docs/create.txt b/src/mailman/commands/docs/create.txt index 7c7b43805..70fb44d8f 100644 --- a/src/mailman/commands/docs/create.txt +++ b/src/mailman/commands/docs/create.txt @@ -35,6 +35,7 @@ the mailing list and domain will be created. Created mailing list: test@example.xx Now both the domain and the mailing list exist in the database. +:: >>> from mailman.interfaces.listmanager import IListManager >>> from zope.component import getUtility @@ -49,6 +50,7 @@ Now both the domain and the mailing list exist in the database. You can also create mailing lists in existing domains without the auto-creation flag. +:: >>> args.domain = False >>> args.listname = ['test1@example.com'] @@ -59,6 +61,7 @@ auto-creation flag. <mailing list "test1@example.com" at ...> The command can also operate quietly. +:: >>> args.quiet = True >>> args.listname = ['test2@example.com'] @@ -79,6 +82,7 @@ By default, no list owners are specified. But you can specify an owner address on the command line when you create the mailing list. +:: >>> args.quiet = False >>> args.listname = ['test4@example.com'] @@ -91,6 +95,7 @@ mailing list. [<Address: foo@example.org [not verified] at ...>] You can even specify more than one address for the owners. +:: >>> args.owners = ['foo@example.net', 'bar@example.net', 'baz@example.net'] >>> args.listname = ['test5@example.com'] @@ -110,6 +115,7 @@ Setting the language You can set the default language for the new mailing list when you create it. The language must be known to Mailman. +:: >>> args.listname = ['test3@example.com'] >>> args.language = 'ee' @@ -142,6 +148,7 @@ When told to, Mailman will notify the list owners of their new mailing list. Created mailing list: test6@example.com The notification message is in the virgin queue. +:: >>> from mailman.testing.helpers import get_queue_messages >>> messages = get_queue_messages('virgin') diff --git a/src/mailman/commands/docs/echo.txt b/src/mailman/commands/docs/echo.txt index 99cb25589..a01172d04 100644 --- a/src/mailman/commands/docs/echo.txt +++ b/src/mailman/commands/docs/echo.txt @@ -13,6 +13,7 @@ to the sender. Echo an acknowledgement. Arguments are return unchanged. The original message is ignored, but the results receive the echoed command. +:: >>> mlist = create_list('test@example.com') diff --git a/src/mailman/commands/docs/import.txt b/src/mailman/commands/docs/import.txt index f1ab072ec..34521026d 100644 --- a/src/mailman/commands/docs/import.txt +++ b/src/mailman/commands/docs/import.txt @@ -4,6 +4,7 @@ Importing list data If you have the config.pck file for a version 2.1 mailing list, you can import that into an existing mailing list in Mailman 3.0. +:: >>> from mailman.commands.cli_import import Import21 >>> command = Import21() @@ -18,6 +19,7 @@ that into an existing mailing list in Mailman 3.0. >>> command.parser = FakeParser() You must specify the mailing list you are importing into, and it must exist. +:: >>> command.process(FakeArgs) List name is required @@ -28,6 +30,7 @@ You must specify the mailing list you are importing into, and it must exist. When the mailing list exists, you must specify a real pickle file to import from. +:: >>> mlist = create_list('import@example.com') >>> command.process(FakeArgs) @@ -39,6 +42,7 @@ from. Now we can import the test pickle file. As a simple illustration of the import, the mailing list's 'real name' has changed. +:: >>> from pkg_resources import resource_filename >>> FakeArgs.pickle_file = [ @@ -50,5 +54,3 @@ import, the mailing list's 'real name' has changed. >>> command.process(FakeArgs) >>> print mlist.real_name Test - -See `../../utilities/docs/importer.txt` for more details. diff --git a/src/mailman/commands/docs/info.txt b/src/mailman/commands/docs/info.txt index d990b514e..85af9325b 100644 --- a/src/mailman/commands/docs/info.txt +++ b/src/mailman/commands/docs/info.txt @@ -3,7 +3,8 @@ Getting information =================== You can get information about Mailman's environment by using the command line -script 'mailman info'. By default, the info is printed to standard output. +script ``mailman info``. By default, the info is printed to standard output. +:: >>> from mailman.commands.cli_info import Info >>> command = Info() @@ -20,7 +21,7 @@ script 'mailman info'. By default, the info is printed to standard output. config file: .../test.cfg db url: sqlite:.../mailman.db -By passing in the -o/--output option, you can print the info to a file. +By passing in the ``-o/--output`` option, you can print the info to a file. >>> from mailman.config import config >>> import os diff --git a/src/mailman/commands/docs/inject.txt b/src/mailman/commands/docs/inject.txt index 189dc1920..e8c405b07 100644 --- a/src/mailman/commands/docs/inject.txt +++ b/src/mailman/commands/docs/inject.txt @@ -4,6 +4,7 @@ Command line message injection You can inject a message directly into a queue directory via the command line. +:: >>> from mailman.commands.cli_inject import Inject >>> command = Inject() @@ -21,6 +22,7 @@ line. >>> command.parser = FakeParser() It's easy to find out which queues are available. +:: >>> args.show = True >>> command.process(args) @@ -63,6 +65,7 @@ However, the mailing list name is always required. List name is required Let's provide a list name and try again. +:: >>> mlist = create_list('test@example.com') >>> transaction.commit() @@ -74,6 +77,7 @@ Let's provide a list name and try again. >>> command.process(args) By default, the incoming queue is used. +:: >>> len(in_queue.files) 1 @@ -98,6 +102,7 @@ By default, the incoming queue is used. version : 3 But a different queue can be specified on the command line. +:: >>> args.queue = 'virgin' >>> command.process(args) @@ -133,6 +138,7 @@ Standard input ============== The message text can also be provided on standard input. +:: >>> from StringIO import StringIO diff --git a/src/mailman/commands/docs/lists.txt b/src/mailman/commands/docs/lists.txt index 887e69bd4..036147a23 100644 --- a/src/mailman/commands/docs/lists.txt +++ b/src/mailman/commands/docs/lists.txt @@ -4,6 +4,7 @@ Command line list display A system administrator can display all the mailing lists via the command line. When there are no mailing lists, a helpful message is displayed. +:: >>> class FakeArgs: ... advertised = False @@ -19,6 +20,7 @@ line. When there are no mailing lists, a helpful message is displayed. When there are a few mailing lists, they are shown in alphabetical order by their fully qualified list names, with a description. +:: >>> from mailman.interfaces.domain import IDomainManager >>> from zope.component import getUtility @@ -45,7 +47,7 @@ Names ===== You can display the mailing list names with their posting addresses, using the ---names/-n switch. +``--names/-n`` switch. >>> FakeArgs.names = True >>> command.process(FakeArgs) @@ -59,7 +61,7 @@ Descriptions ============ You can also display the mailing list descriptions, using the ---descriptions/-d option. +``--descriptions/-d`` option. >>> FakeArgs.descriptions = True >>> command.process(FakeArgs) @@ -81,7 +83,7 @@ Maybe you want the descriptions but not the names. Less verbosity ============== -There's also a --quiet/-q switch which reduces the verbosity a bit. +There's also a ``--quiet/-q`` switch which reduces the verbosity a bit. >>> FakeArgs.quiet = True >>> FakeArgs.descriptions = False @@ -127,6 +129,7 @@ Advertised lists Mailing lists can be 'advertised' meaning their existence is public knowledge. Non-advertised lists are considered private. Display through the command line can select on this attribute. +:: >>> FakeArgs.domains = [] >>> FakeArgs.advertised = True diff --git a/src/mailman/commands/docs/members.txt b/src/mailman/commands/docs/members.txt index af7f13da7..602e1bbe5 100644 --- a/src/mailman/commands/docs/members.txt +++ b/src/mailman/commands/docs/members.txt @@ -2,8 +2,9 @@ Managing members ================ -The `bin/mailman members` command allows a site administrator to display, add, -and remove members from a mailing list. +The ``bin/mailman members`` command allows a site administrator to display, +add, and remove members from a mailing list. +:: >>> mlist1 = create_list('test1@example.com') @@ -31,6 +32,7 @@ options. To start with, there are no members of the mailing list. test1@example.com has no members Once the mailing list add some members, they will be displayed. +:: >>> from mailman.interfaces.member import DeliveryMode >>> from mailman.app.membership import add_member @@ -48,6 +50,7 @@ Once the mailing list add some members, they will be displayed. Bart Person <bart@example.com> Members are displayed in alphabetical order based on their address. +:: >>> add_member(mlist1, 'anne@aaaxample.com', 'Anne Person', 'xxx', ... DeliveryMode.regular, mlist1.preferred_language.code) @@ -114,6 +117,7 @@ members... Anne Person <anne@example.com> ...just MIME digest members. +:: >>> args.digest = 'mime' >>> command.process(args) @@ -129,6 +133,7 @@ Filtering on delivery status You can also filter the display on the member's delivery status. By default, all members are displayed, but you can filter out only those whose delivery status is enabled... +:: >>> from mailman.interfaces.member import DeliveryStatus >>> member = mlist1.members.get_member('anne@aaaxample.com') @@ -178,6 +183,7 @@ status is enabled... Cris Person <cris@example.com> You can also display all members who have delivery disabled for any reason. +:: >>> args.nomail = 'any' >>> command.process(args) @@ -195,7 +201,8 @@ Adding members You can add members to a mailing list from the command line. To do so, you need a file containing email addresses and full names that can be parsed by -email.utils.parseaddr(). +``email.utils.parseaddr()``. +:: >>> mlist2 = create_list('test2@example.com') >>> addresses = [ @@ -217,8 +224,9 @@ email.utils.parseaddr(). >>> sorted(address.address for address in mlist2.members.addresses) [u'aperson@example.com', u'bperson@example.com', u'cperson@example.com'] -You can also specify '-' as the filename, in which case the addresses are +You can also specify ``-`` as the filename, in which case the addresses are taken from standard input. +:: >>> from StringIO import StringIO >>> fp = StringIO() @@ -241,6 +249,7 @@ taken from standard input. u'dperson@example.com', u'eperson@example.com', u'fperson@example.com'] Blank lines and lines that begin with '#' are ignored. +:: >>> with open(path, 'w') as fp: ... for address in ('gperson@example.com', @@ -260,6 +269,7 @@ Blank lines and lines that begin with '#' are ignored. Addresses which are already subscribed are ignored, although a warning is printed. +:: >>> with open(path, 'w') as fp: ... for address in ('gperson@example.com', diff --git a/src/mailman/commands/docs/membership.txt b/src/mailman/commands/docs/membership.txt index a0af15ba7..3d611a160 100644 --- a/src/mailman/commands/docs/membership.txt +++ b/src/mailman/commands/docs/membership.txt @@ -3,15 +3,15 @@ Membership changes via email ============================ Membership changes such as joining and leaving a mailing list, can be effected -via the email interface. The Mailman email commands 'join', 'leave', and -'confirm' are used. +via the email interface. The Mailman email commands ``join``, ``leave``, and +``confirm`` are used. Joining a mailing list ====================== -The mail command 'join' subscribes an email address to the mailing list. -'subscribe' is an alias for 'join'. +The mail command ``join`` subscribes an email address to the mailing list. +``subscribe`` is an alias for ``join``. >>> from mailman.commands.eml_membership import Join >>> join = Join() @@ -39,6 +39,7 @@ No address to join When no address argument is given, the message's From address will be used. If that's missing though, then an error is returned. +:: >>> from mailman.queue.command import Results >>> results = Results() @@ -52,7 +53,7 @@ If that's missing though, then an error is returned. join: No valid address found to subscribe <BLANKLINE> -The 'subscribe' command is an alias. +The ``subscribe`` command is an alias. >>> from mailman.commands.eml_membership import Subscribe >>> subscribe = Subscribe() @@ -133,6 +134,7 @@ Mailman has sent her the confirmation message. Once Anne confirms her registration, she will be made a member of the mailing list. +:: >>> def extract_token(message): ... return str(message['subject']).split()[1].strip() @@ -190,7 +192,9 @@ But she is not a member of the mailing list. >>> print mlist_2.members.get_member('anne@example.com') None -One Anne confirms this subscription, she becomes a member of the mailing list. +One Anne confirms this subscription, she becomes a member of the mailing +list. +:: >>> items = get_queue_messages('virgin') >>> len(items) @@ -220,8 +224,8 @@ One Anne confirms this subscription, she becomes a member of the mailing list. Leaving a mailing list ====================== -The mail command 'leave' unsubscribes an email address from the mailing list. -'unsubscribe' is an alias for 'leave'. +The mail command ``leave`` unsubscribes an email address from the mailing +list. ``unsubscribe`` is an alias for ``leave``. >>> from mailman.commands.eml_membership import Leave >>> leave = Leave() @@ -230,9 +234,9 @@ The mail command 'leave' unsubscribes an email address from the mailing list. >>> print leave.description Leave this mailing list. You will be asked to confirm your request. -Anne is a member of the baker@example.com mailing list, when she decides to -leave it. She sends a message to the -leave address for the list and is sent -a confirmation message for her request. +Anne is a member of the ``baker@example.com`` mailing list, when she decides +to leave it. She sends a message to the ``-leave`` address for the list and +is sent a confirmation message for her request. >>> results = Results() >>> print leave.process(mlist_2, msg, {}, (), results) @@ -251,6 +255,7 @@ Anne is no longer a member of the mailing list. Anne does not need to leave a mailing list with the same email address she's subscribe with. Any of her registered, linked, and validated email addresses will do. +:: >>> anne = user_manager.get_user('anne@example.com') >>> address = anne.register('anne.person@example.org') @@ -268,6 +273,7 @@ will do. Since Anne's alternative address has not yet been verified, it can't be used to unsubscribe Anne from the alpha mailing list. +:: >>> print leave.process(mlist, msg, {}, (), results) ContinueProcessing.no @@ -284,6 +290,7 @@ to unsubscribe Anne from the alpha mailing list. Once Anne has verified her alternative address though, it can be used to unsubscribe her from the list. +:: >>> from datetime import datetime >>> address.verified_on = datetime.now() @@ -306,6 +313,7 @@ Confirmations ============= Bart wants to join the alpha list, so he sends his subscription request. +:: >>> msg = message_from_string("""\ ... From: Bart Person <bart@example.com> @@ -333,6 +341,7 @@ Bart is still not a user. Bart replies to the original message, specifically keeping the Subject header intact except for any prefix. Mailman matches the token and confirms Bart as a user of the system. +:: >>> msg = message_from_string("""\ ... From: Bart Person <bart@example.com> diff --git a/src/mailman/commands/docs/qfile.txt b/src/mailman/commands/docs/qfile.txt index c54f37c50..74ede1b64 100644 --- a/src/mailman/commands/docs/qfile.txt +++ b/src/mailman/commands/docs/qfile.txt @@ -2,7 +2,7 @@ Dumping queue files =================== -The 'qfile' command dumps the contents of a queue pickle file. This is +The ``qfile`` command dumps the contents of a queue pickle file. This is especially useful when you have shunt files you want to inspect. XXX Test the interactive operation of qfile @@ -11,8 +11,9 @@ XXX Test the interactive operation of qfile Pretty printing =============== -By default, the qfile command pretty prints the contents of a queue pickle +By default, the ``qfile`` command pretty prints the contents of a queue pickle file to standard output. +:: >>> from mailman.commands.cli_qfile import QFile >>> command = QFile() @@ -23,6 +24,7 @@ file to standard output. ... qfile = [] Let's say Mailman shunted a message file. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -36,6 +38,7 @@ Let's say Mailman shunted a message file. >>> basename = shuntq.enqueue(msg, foo=7, bar='baz', bad='yes') Once we've figured out the file name of the shunted message, we can print it. +:: >>> from os.path import join >>> qfile = join(shuntq.queue_directory, basename + '.pck') diff --git a/src/mailman/commands/docs/remove.txt b/src/mailman/commands/docs/remove.txt index 0158c9b37..f0f4e64f6 100644 --- a/src/mailman/commands/docs/remove.txt +++ b/src/mailman/commands/docs/remove.txt @@ -3,6 +3,7 @@ Command line list removal ========================= A system administrator can remove mailing lists by the command line. +:: >>> create_list('test@example.com') <mailing list "test@example.com" at ...> @@ -29,6 +30,7 @@ A system administrator can remove mailing lists by the command line. None You can also remove lists quietly. +:: >>> create_list('test@example.com') <mailing list "test@example.com" at ...> @@ -44,6 +46,7 @@ Removing archives ================= By default 'mailman remove' does not remove a mailing list's archives. +:: >>> create_list('test@example.com') <mailing list "test@example.com" at ...> @@ -71,6 +74,7 @@ By default 'mailman remove' does not remove a mailing list's archives. Even if the mailing list has been deleted, you can still delete the archives afterward. +:: >>> args.archives = True diff --git a/src/mailman/commands/docs/unshunt.txt b/src/mailman/commands/docs/unshunt.txt index dcf71f3d1..ce9d70316 100644 --- a/src/mailman/commands/docs/unshunt.txt +++ b/src/mailman/commands/docs/unshunt.txt @@ -3,8 +3,9 @@ Unshunt ======= When errors occur while processing email messages, the messages will end up in -the 'shunt' queue. The 'unshunt' command allows system administrators to +the ``shunt`` queue. The ``unshunt`` command allows system administrators to manage the shunt queue. +:: >>> from mailman.commands.cli_unshunt import Unshunt >>> command = Unshunt() @@ -13,6 +14,7 @@ manage the shunt queue. ... discard = False Let's say there is a message in the shunt queue. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -29,7 +31,9 @@ Let's say there is a message in the shunt queue. >>> len(list(shuntq.files)) 1 -The unshunt command by default moves the message back to the incoming queue. +The ``unshunt`` command by default moves the message back to the incoming +queue. +:: >>> inq = config.switchboards['in'] >>> len(list(inq.files)) @@ -49,7 +53,8 @@ The unshunt command by default moves the message back to the incoming queue. <BLANKLINE> <BLANKLINE> -'unshunt' moves all shunt queue messages. +``unshunt`` moves all shunt queue messages. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -97,6 +102,7 @@ different queue, it will be returned to the queue it came from. ... """) The queue that the message comes from is in message metadata. +:: >>> base_name = shuntq.enqueue(msg, {}, whichq='bounces') @@ -106,6 +112,7 @@ The queue that the message comes from is in message metadata. 0 The message is automatically re-queued to the bounces queue. +:: >>> command.process(FakeArgs) >>> len(list(shuntq.files)) @@ -127,6 +134,7 @@ Discarding all shunted messages =============================== If you don't care about the shunted messages, just discard them. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com diff --git a/src/mailman/commands/docs/version.txt b/src/mailman/commands/docs/version.txt index 9987066e9..8032df20a 100644 --- a/src/mailman/commands/docs/version.txt +++ b/src/mailman/commands/docs/version.txt @@ -3,6 +3,7 @@ Printing the version ==================== You can print the Mailman version number. +:: >>> from mailman.commands.cli_version import Version >>> command = Version() diff --git a/src/mailman/commands/docs/withlist.txt b/src/mailman/commands/docs/withlist.txt index f85607ab9..7632c726a 100644 --- a/src/mailman/commands/docs/withlist.txt +++ b/src/mailman/commands/docs/withlist.txt @@ -2,7 +2,7 @@ Operating on mailing lists ========================== -The 'withlist' command is a pretty powerful way to operate on mailing lists +The ``withlist`` command is a pretty powerful way to operate on mailing lists from the command line. This command allows you to interact with a list at a Python prompt, or process one or more mailing lists through custom made Python functions. @@ -13,7 +13,8 @@ XXX Test the interactive operation of withlist Getting detailed help ===================== -Because withlist is so complex, you need to request detailed help. +Because ``withlist`` is so complex, you need to request detailed help. +:: >>> from mailman.commands.cli_withlist import Withlist >>> command = Withlist() @@ -39,9 +40,10 @@ Because withlist is so complex, you need to request detailed help. Running a command ================= -By putting a Python function somewhere on your sys.path, you can have withlist -call that function on a given mailing list. The function takes a single -argument, the mailing list. +By putting a Python function somewhere on your ``sys.path``, you can have +``withlist`` call that function on a given mailing list. The function takes a +single argument, the mailing list. +:: >>> import os, sys >>> old_path = sys.path[:] @@ -78,8 +80,9 @@ Multiple lists ============== You can run a command over more than one list by using a regular expression in -the LISTNAME argument. To indicate a regular expression is used, the string +the `listname` argument. To indicate a regular expression is used, the string must start with a caret. +:: >>> mlist_2 = create_list('badger@example.com') >>> mlist_3 = create_list('badboys@example.com') diff --git a/src/mailman/model/docs/addresses.txt b/src/mailman/model/docs/addresses.txt index 5388a3cc8..aeddb5e31 100644 --- a/src/mailman/model/docs/addresses.txt +++ b/src/mailman/model/docs/addresses.txt @@ -41,8 +41,8 @@ You can also create an email address object with a real name. >>> sorted(address.real_name for address in user_manager.addresses) [u'', u'Ben Person'] -The str() of the address is the RFC 2822 preferred originator format, while -the repr() carries more information. +The ``str()`` of the address is the RFC 2822 preferred originator format, +while the ``repr()`` carries more information. >>> str(address_2) 'Ben Person <bperson@example.com>' @@ -149,6 +149,7 @@ Subscriptions Addresses get subscribed to mailing lists, not users. When the address is subscribed, a role is specified. +:: >>> address_5 = user_manager.create_address( ... 'eperson@example.com', 'Elly Person') diff --git a/src/mailman/model/docs/autorespond.txt b/src/mailman/model/docs/autorespond.txt index ba0521a89..3a9ad01b2 100644 --- a/src/mailman/model/docs/autorespond.txt +++ b/src/mailman/model/docs/autorespond.txt @@ -3,11 +3,12 @@ Automatic responder =================== In various situations, Mailman will send an automatic response to the author -of an email message. For example, if someone sends a command to the -request -address, Mailman will send a response, but to cut down on third party spam, -the sender will only get a certain number of responses per day. +of an email message. For example, if someone sends a command to the +``-request`` address, Mailman will send a response, but to cut down on third +party spam, the sender will only get a certain number of responses per day. -First, given a mailing list you need to adapt it to an IAutoResponseSet. +First, given a mailing list you need to adapt it to an ``IAutoResponseSet``. +:: >>> mlist = create_list('test@example.com') >>> from mailman.interfaces.autorespond import IAutoResponseSet @@ -17,7 +18,7 @@ First, given a mailing list you need to adapt it to an IAutoResponseSet. >>> verifyObject(IAutoResponseSet, response_set) True -You can't adapt other objects to an IAutoResponseSet. +You can't adapt other objects to an ``IAutoResponseSet``. >>> IAutoResponseSet(object()) Traceback (most recent call last): @@ -28,6 +29,7 @@ There are various kinds of response types. For example, Mailman will send an automatic response when messages are held for approval, or when it receives an email command. You can find out how many responses for a particular address have already been sent today. +:: >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility @@ -66,6 +68,7 @@ Let's send one more. 2 Now the day flips over and all the counts reset. +:: >>> from mailman.utilities.datetime import factory >>> factory.fast_forward() @@ -92,6 +95,7 @@ You can also use the response set to get the date of the last response sent. datetime.date(2005, 8, 1) When another response is sent today, that becomes the last one sent. +:: >>> response_set.response_sent(address, Response.command) >>> response_set.last_response(address, Response.command).date_sent diff --git a/src/mailman/model/docs/domains.txt b/src/mailman/model/docs/domains.txt index 5673e6ee9..9fe43a5f1 100644 --- a/src/mailman/model/docs/domains.txt +++ b/src/mailman/model/docs/domains.txt @@ -2,7 +2,7 @@ Domains ======= - # The test framework starts out with an example domain, so let's delete +.. # The test framework starts out with an example domain, so let's delete # that first. >>> from mailman.interfaces.domain import IDomainManager >>> from zope.component import getUtility @@ -11,6 +11,7 @@ Domains <Domain example.com...> Domains are how Mailman interacts with email host names and web host names. +:: >>> from operator import attrgetter >>> def show_domains(): @@ -52,6 +53,7 @@ web interface for the domain. contact_address: postmaster@example.com> Domains can have explicit descriptions and contact addresses. +:: >>> manager.add( ... 'example.net', @@ -70,6 +72,7 @@ Domains can have explicit descriptions and contact addresses. contact_address: postmaster@example.com> In the global domain manager, domains are indexed by their email host name. +:: >>> for domain in sorted(manager, key=attrgetter('email_host')): ... print domain.email_host @@ -87,7 +90,8 @@ In the global domain manager, domains are indexed by their email host name. KeyError: u'doesnotexist.com' As with a dictionary, you can also get the domain. If the domain does not -exist, None or a default is returned. +exist, ``None`` or a default is returned. +:: >>> print manager.get('example.net') <Domain example.net, The example domain, diff --git a/src/mailman/model/docs/languages.txt b/src/mailman/model/docs/languages.txt index a724a0510..21143f28b 100644 --- a/src/mailman/model/docs/languages.txt +++ b/src/mailman/model/docs/languages.txt @@ -5,6 +5,7 @@ Languages Mailman is multilingual. A language manager handles the known set of languages at run time, as well as enabling those languages for use in a running Mailman instance. +:: >>> from mailman.interfaces.languages import ILanguageManager >>> from zope.component import getUtility @@ -94,6 +95,7 @@ Clearing the known languages ============================ The language manager can forget about all the language codes it knows about. +:: >>> 'en' in mgr True diff --git a/src/mailman/model/docs/listmanager.txt b/src/mailman/model/docs/listmanager.txt index e07659066..7235049c7 100644 --- a/src/mailman/model/docs/listmanager.txt +++ b/src/mailman/model/docs/listmanager.txt @@ -2,10 +2,8 @@ The mailing list manager ======================== -The IListManager is how you create, delete, and retrieve mailing list -objects. The Mailman system instantiates an IListManager for you based on the -configuration variable MANAGERS_INIT_FUNCTION. The instance is accessible -on the global config object. +The ``IListManager`` is how you create, delete, and retrieve mailing list +objects. >>> from mailman.interfaces.listmanager import IListManager >>> from zope.component import getUtility @@ -76,12 +74,12 @@ always get the same object back. >>> mlist_2 is mlist True -If you try to get a list that doesn't existing yet, you get None. +If you try to get a list that doesn't existing yet, you get ``None``. >>> print list_manager.get('_xtest_2@example.com') None -You also get None if the list name is invalid. +You also get ``None`` if the list name is invalid. >>> print list_manager.get('foo') None diff --git a/src/mailman/model/docs/mailinglist.txt b/src/mailman/model/docs/mailinglist.txt index 687f7b39c..33d681762 100644 --- a/src/mailman/model/docs/mailinglist.txt +++ b/src/mailman/model/docs/mailinglist.txt @@ -2,7 +2,7 @@ Mailing lists ============= -XXX 2010-06-18 BAW: This documentation needs a lot more detail. +.. XXX 2010-06-18 BAW: This documentation needs a lot more detail. The mailing list is a core object in Mailman. It is uniquely identified in the system by its posting address, i.e. the email address you would send a @@ -25,10 +25,11 @@ name (i.e. local part) and host name. Rosters ======= -Mailing list membership is represented by 'rosters'. Each mailing list has +Mailing list membership is represented by `rosters`. Each mailing list has several rosters of members, representing the subscribers to the mailing list, the owners, the moderators, and so on. The rosters are defined by a membership role. +:: >>> from mailman.interfaces.member import MemberRole >>> from mailman.testing.helpers import subscribe diff --git a/src/mailman/model/docs/membership.txt b/src/mailman/model/docs/membership.txt index 41660f0d2..a3782eef6 100644 --- a/src/mailman/model/docs/membership.txt +++ b/src/mailman/model/docs/membership.txt @@ -4,7 +4,7 @@ List memberships Users represent people in Mailman. Users control email addresses, and rosters are collections of members. A member gives an email address a role, such as -'member', 'administrator', or 'moderator'. Roster sets are collections of +`member`, `administrator`, or `moderator`. Roster sets are collections of rosters and a mailing list has a single roster set that contains all its members, regardless of that member's role. @@ -180,8 +180,8 @@ It's easy to make the list administrators members of the mailing list too. Finding members =============== -You can find the IMember object that is a member of a roster for a given text -email address by using an IRoster's .get_member() method. +You can find the ``IMember`` object that is a member of a roster for a given +text email address by using the ``IRoster.get_member()`` method. >>> mlist.owners.get_member('aperson@example.com') <Member: Anne Person <aperson@example.com> on diff --git a/src/mailman/model/docs/messagestore.txt b/src/mailman/model/docs/messagestore.txt index aabfd55fb..3ee59129b 100644 --- a/src/mailman/model/docs/messagestore.txt +++ b/src/mailman/model/docs/messagestore.txt @@ -2,17 +2,17 @@ The message store ================= -The message store is a collection of messages keyed off of Message-ID and -X-Message-ID-Hash headers. Either of these values can be combined with the -message's List-Archive header to create a globally unique URI to the message -object in the internet facing interface of the message store. The -X-Message-ID-Hash is the Base32 SHA1 hash of the Message-ID. +The message store is a collection of messages keyed off of ``Message-ID`` and +``X-Message-ID-Hash`` headers. Either of these values can be combined with +the message's ``List-Archive`` header to create a globally unique URI to the +message object in the internet facing interface of the message store. The +``X-Message-ID-Hash`` is the Base32 SHA1 hash of the ``Message-ID``. >>> from mailman.interfaces.messages import IMessageStore >>> from zope.component import getUtility >>> message_store = getUtility(IMessageStore) -If you try to add a message to the store which is missing the Message-ID +If you try to add a message to the store which is missing the ``Message-ID`` header, you will get an exception. >>> msg = message_from_string("""\ @@ -25,7 +25,7 @@ header, you will get an exception. ... ValueError: Exactly one Message-ID header required -However, if the message has a Message-ID header, it can be stored. +However, if the message has a ``Message-ID`` header, it can be stored. >>> msg['Message-ID'] = '<87myycy5eh.fsf@uwakimon.sk.tsukuba.ac.jp>' >>> message_store.add(msg) @@ -42,16 +42,16 @@ However, if the message has a Message-ID header, it can be stored. Finding messages ================ -There are several ways to find a message given either the Message-ID or -X-Message-ID-Hash headers. In either case, if no matching message is found, -None is returned. +There are several ways to find a message given either the ``Message-ID`` or +``X-Message-ID-Hash`` headers. In either case, if no matching message is +found, ``None`` is returned. >>> print message_store.get_message_by_id('nothing') None >>> print message_store.get_message_by_hash('nothing') None -Given an existing Message-ID, the message can be found. +Given an existing ``Message-ID``, the message can be found. >>> message = message_store.get_message_by_id(msg['message-id']) >>> print message.as_string() @@ -62,7 +62,7 @@ Given an existing Message-ID, the message can be found. This message is very important. <BLANKLINE> -Similarly, we can find messages by the X-Message-ID-Hash: +Similarly, we can find messages by the ``X-Message-ID-Hash``: >>> message = message_store.get_message_by_hash(msg['x-message-id-hash']) >>> print message.as_string() @@ -95,9 +95,9 @@ contains. Deleting messages from the store ================================ -You delete a message from the storage service by providing the Message-ID for -the message you want to delete. If you try to delete a Message-ID that isn't -in the store, you get an exception. +You delete a message from the storage service by providing the ``Message-ID`` +for the message you want to delete. If you try to delete a ``Message-ID`` +that isn't in the store, you get an exception. >>> message_store.delete_message('nothing') Traceback (most recent call last): diff --git a/src/mailman/model/docs/mlist-addresses.txt b/src/mailman/model/docs/mlist-addresses.txt index 3f44008fb..2a021f67f 100644 --- a/src/mailman/model/docs/mlist-addresses.txt +++ b/src/mailman/model/docs/mlist-addresses.txt @@ -3,7 +3,7 @@ Mailing list addresses ====================== Every mailing list has a number of addresses which are publicly available. -These are defined in the IMailingListAddresses interface. +These are defined in the ``IMailingListAddresses`` interface. >>> mlist = create_list('_xtest@example.com') @@ -15,7 +15,7 @@ list. This is exactly the same as the fully qualified list name. >>> print mlist.posting_address _xtest@example.com -Messages to the mailing list's 'no reply' address always get discarded without +Messages to the mailing list's `no reply` address always get discarded without prejudice. >>> print mlist.no_reply_address @@ -61,7 +61,8 @@ Email confirmations Email confirmation messages are sent when actions such as subscriptions need to be confirmed. It requires that a cookie be provided, which will be included in the local part of the email address. The exact format of this is -dependent on the VERP_CONFIRM_FORMAT configuration variable. +dependent on the ``verp_confirm_format`` configuration variable. +:: >>> print mlist.confirm_address('cookie') _xtest-confirm+cookie@example.com diff --git a/src/mailman/model/docs/pending.txt b/src/mailman/model/docs/pending.txt index dc27b6bee..e85d8e484 100644 --- a/src/mailman/model/docs/pending.txt +++ b/src/mailman/model/docs/pending.txt @@ -17,8 +17,8 @@ available by adapting the list manager. >>> from zope.component import getUtility >>> pendingdb = getUtility(IPendings) -The pending database can add any IPendable to the database, returning a token -that can be used in urls and such. +The pending database can add any ``IPendable`` to the database, returning a +token that can be used in urls and such. >>> from mailman.interfaces.pending import IPendable >>> class SimplePendable(dict): @@ -33,10 +33,10 @@ that can be used in urls and such. >>> len(token) 40 -There's not much you can do with tokens except to 'confirm' them, which -basically means returning the IPendable structure (as a dict) from the -database that matches the token. If the token isn't in the database, None is -returned. +There's not much you can do with tokens except to `confirm` them, which +basically means returning the ``IPendable`` structure (as a dictionary) from +the database that matches the token. If the token isn't in the database, +``None`` is returned. >>> pendable = pendingdb.confirm(bytes('missing')) >>> print pendable @@ -56,7 +56,7 @@ After confirmation, the token is no longer in the database. None There are a few other things you can do with the pending database. When you -confirm a token, you can leave it in the database, or in otherwords, not +confirm a token, you can leave it in the database, or in other words, not expunge it. >>> event_1 = SimplePendable(type='one') diff --git a/src/mailman/model/docs/registration.txt b/src/mailman/model/docs/registration.txt index abc7f2c93..050a4d0f3 100644 --- a/src/mailman/model/docs/registration.txt +++ b/src/mailman/model/docs/registration.txt @@ -7,10 +7,10 @@ The only thing they must supply is an email address, although there is additional information they may supply. All registered email addresses must be verified before Mailman will send them any list traffic. -The IUserManager manages users, but it does so at a fairly low level. +The ``IUserManager`` manages users, but it does so at a fairly low level. Specifically, it does not handle verifications, email address syntax validity -checks, etc. The IRegistrar is the interface to the object handling all this -stuff. +checks, etc. The ``IRegistrar`` is the interface to the object handling all +this stuff. >>> from mailman.interfaces.registrar import IRegistrar >>> from zope.component import getUtility @@ -76,9 +76,9 @@ Register an email address ========================= Registration of an unknown address creates nothing until the confirmation step -is complete. No IUser or IAddress is created at registration time, but a -record is added to the pending database, and the token for that record is -returned. +is complete. No ``IUser`` or ``IAddress`` is created at registration time, +but a record is added to the pending database, and the token for that record +is returned. >>> token = registrar.register(mlist, 'aperson@example.com', 'Anne Person') >>> check_token(token) @@ -161,12 +161,12 @@ appear in a URL in the body of the message. >>> sent_token == token True -The same token will appear in the From header. +The same token will appear in the ``From`` header. >>> items[0].msg['from'] == 'alpha-confirm+' + token + '@example.com' True -It will also appear in the Subject header. +It will also appear in the ``Subject`` header. >>> items[0].msg['subject'] == 'confirm ' + token True @@ -178,8 +178,8 @@ token and uses that to confirm the pending registration. >>> registrar.confirm(token) True -Now, there is an IAddress in the database matching the address, as well as an -IUser linked to this address. The IAddress is verified. +Now, there is an ``IAddress`` in the database matching the address, as well as +an ``IUser`` linked to this address. The ``IAddress`` is verified. >>> found_address = user_manager.get_address('aperson@example.com') >>> found_address @@ -247,7 +247,9 @@ Discarding ========== A confirmation token can also be discarded, say if the user changes his or her -mind about registering. When discarded, no IAddress or IUser is created. +mind about registering. When discarded, no ``IAddress`` or ``IUser`` is +created. +:: >>> token = registrar.register(mlist, 'eperson@example.com', 'Elly Person') >>> check_token(token) @@ -270,6 +272,7 @@ Registering a new address for an existing user When a new address for an existing user is registered, there isn't too much different except that the new address will still need to be verified before it can be used. +:: >>> dperson = user_manager.create_user( ... 'dperson@example.com', 'Dave Person') @@ -310,9 +313,9 @@ confirm method will just return False. >>> registrar.confirm(bytes('no token')) False -Likewise, if you try to confirm, through the IUserRegistrar interface, a token -that doesn't match a registration event, you will get None. However, the -pending event matched with that token will still be removed. +Likewise, if you try to confirm, through the ``IUserRegistrar`` interface, a +token that doesn't match a registration event, you will get ``None``. +However, the pending event matched with that token will still be removed. >>> from mailman.interfaces.pending import IPendable >>> from zope.interface import implements diff --git a/src/mailman/model/docs/requests.txt b/src/mailman/model/docs/requests.txt index 8cd027297..6cca8f602 100644 --- a/src/mailman/model/docs/requests.txt +++ b/src/mailman/model/docs/requests.txt @@ -35,6 +35,7 @@ Mailing list centric A set of requests are always related to a particular mailing list, so given a mailing list you need to get its requests object. +:: >>> from mailman.interfaces.requests import IListRequests, IRequests >>> from zope.component import getUtility @@ -203,10 +204,10 @@ For the next section, we first clean up all the current requests. Application support =================== -There are several higher level interfaces available in the mailman.app package -which can be used to hold messages, subscription, and unsubscriptions. There -are also interfaces for disposing of these requests in an application specific -and consistent way. +There are several higher level interfaces available in the ``mailman.app`` +package which can be used to hold messages, subscription, and unsubscriptions. +There are also interfaces for disposing of these requests in an application +specific and consistent way. >>> from mailman.app import moderator @@ -237,6 +238,7 @@ this case, we won't include any additional metadata. True We can also hold a message with some additional metadata. +:: # Delete the Message-ID from the previous hold so we don't try to store # collisions in the message storage. @@ -336,6 +338,7 @@ re-added to the message store). When handling a message, we can tell the moderator interface to also preserve a copy, essentially telling it not to delete the message from the storage. First, without the switch, the message is deleted. +:: >>> msg = message_from_string("""\ ... From: aperson@example.org @@ -374,6 +377,7 @@ the message store after disposition. Orthogonal to preservation, the message can also be forwarded to another address. This is helpful for getting the message into the inbox of one of the moderators. +:: # Set a new Message-ID from the previous hold so we don't try to store # collisions in the message storage. @@ -678,6 +682,7 @@ The admin message is sent to the moderators. version : 3 Frank Person is now a member of the mailing list. +:: >>> member = mlist.members.get_member('fperson@example.org') >>> member @@ -704,7 +709,9 @@ Holding unsubscription requests Some lists, though it is rare, require moderator approval for unsubscriptions. In this case, only the unsubscribing address is required. Like subscriptions, -unsubscription holds can send the list's moderators an immediate notification. +unsubscription holds can send the list's moderators an immediate +notification. +:: >>> mlist.admin_immed_notify = False >>> from mailman.interfaces.member import MemberRole @@ -776,6 +783,7 @@ subscribed. The request can be rejected, in which case a message is sent to the member, and the person remains a member of the mailing list. +:: >>> moderator.handle_unsubscription(mlist, id_6, Action.reject, ... 'This list is a prison.') diff --git a/src/mailman/model/docs/usermanager.txt b/src/mailman/model/docs/usermanager.txt index 856221952..a6bd4fed2 100644 --- a/src/mailman/model/docs/usermanager.txt +++ b/src/mailman/model/docs/usermanager.txt @@ -2,10 +2,7 @@ The user manager ================ -The IUserManager is how you create, delete, and manage users. The Mailman -system instantiates an IUserManager for you based on the configuration -variable MANAGERS_INIT_FUNCTION. The instance is accessible on the global -config object. +The ``IUserManager`` is how you create, delete, and manage users. >>> from mailman.interfaces.usermanager import IUserManager >>> from zope.component import getUtility @@ -16,9 +13,10 @@ Creating users ============== There are several ways you can create a user object. The simplest is to -create a 'blank' user by not providing an address or real name at creation +create a `blank` user by not providing an address or real name at creation time. This user will have an empty string as their real name, but will not have a password. +:: >>> from mailman.interfaces.user import IUser >>> from zope.interface.verify import verifyObject @@ -103,10 +101,10 @@ longer available through the user manager iterator. Finding users ============= -You can ask the user manager to find the IUser that controls a particular +You can ask the user manager to find the ``IUser`` that controls a particular email address. You'll get back the original user object if it's found. Note -that the .get_user() method takes a string email address, not an IAddress -object. +that the ``.get_user()`` method takes a string email address, not an +``IAddress`` object. >>> address = list(user_4.addresses)[0] >>> found_user = user_manager.get_user(address.address) @@ -116,7 +114,7 @@ object. True If the address is not in the user database or does not have a user associated -with it, you will get None back. +with it, you will get ``None`` back. >>> print user_manager.get_user('zperson@example.com') None diff --git a/src/mailman/model/docs/users.txt b/src/mailman/model/docs/users.txt index bb0301772..b36c250f9 100644 --- a/src/mailman/model/docs/users.txt +++ b/src/mailman/model/docs/users.txt @@ -133,7 +133,9 @@ Users have preferences, but these preferences have no default settings. receive_own_postings : None delivery_mode : None -Some of these preferences are booleans and they can be set to True or False. +Some of these preferences are booleans and they can be set to ``True`` or +``False``. +:: >>> from mailman.interfaces.languages import ILanguageManager >>> getUtility(ILanguageManager).add('it', 'iso-8859-1', 'Italian') @@ -158,6 +160,7 @@ Subscriptions Users know which mailing lists they are subscribed to, regardless of membership role. +:: >>> user_1.link(address_1) >>> sorted(address.address for address in user_1.addresses) @@ -201,8 +204,4 @@ membership role. zperson@example.org xtest_2@example.com MemberRole.owner -Cross references -================ - .. _`usermanager.txt`: usermanager.html - diff --git a/src/mailman/pipeline/docs/ack-headers.txt b/src/mailman/pipeline/docs/ack-headers.txt index 0f4d8ab9e..dba2169e2 100644 --- a/src/mailman/pipeline/docs/ack-headers.txt +++ b/src/mailman/pipeline/docs/ack-headers.txt @@ -2,7 +2,7 @@ Acknowledgment headers ====================== -Messages that flow through the global pipeline get their headers 'cooked', +Messages that flow through the global pipeline get their headers `cooked`, which basically means that their headers go through several mostly unrelated transformations. Some headers get added, others get changed. Some of these changes depend on mailing list settings and others depend on how the message @@ -11,8 +11,9 @@ is getting sent through the system. We'll take things one-by-one. >>> mlist = create_list('_xtest@example.com') >>> mlist.subject_prefix = '' -When the message's metadata has a 'noack' key set, an 'X-Ack: no' header is +When the message's metadata has a `noack` key set, an ``X-Ack: no`` header is added. +:: >>> msg = message_from_string("""\ ... From: aperson@example.com @@ -27,7 +28,7 @@ added. X-Ack: no ... -Any existing X-Ack header in the original message is removed. +Any existing ``X-Ack`` header in the original message is removed. >>> msg = message_from_string("""\ ... X-Ack: yes |