diff options
Diffstat (limited to 'src/mailman/commands')
| -rw-r--r-- | src/mailman/commands/docs/create.txt | 7 | ||||
| -rw-r--r-- | src/mailman/commands/docs/echo.txt | 1 | ||||
| -rw-r--r-- | src/mailman/commands/docs/import.txt | 6 | ||||
| -rw-r--r-- | src/mailman/commands/docs/info.txt | 5 | ||||
| -rw-r--r-- | src/mailman/commands/docs/inject.txt | 6 | ||||
| -rw-r--r-- | src/mailman/commands/docs/lists.txt | 9 | ||||
| -rw-r--r-- | src/mailman/commands/docs/members.txt | 18 | ||||
| -rw-r--r-- | src/mailman/commands/docs/membership.txt | 31 | ||||
| -rw-r--r-- | src/mailman/commands/docs/qfile.txt | 7 | ||||
| -rw-r--r-- | src/mailman/commands/docs/remove.txt | 4 | ||||
| -rw-r--r-- | src/mailman/commands/docs/unshunt.txt | 14 | ||||
| -rw-r--r-- | src/mailman/commands/docs/version.txt | 1 | ||||
| -rw-r--r-- | src/mailman/commands/docs/withlist.txt | 15 |
13 files changed, 91 insertions, 33 deletions
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') |