Commit 863de88b authored by Mark Sapiro's avatar Mark Sapiro

Merge branch 'docs' into 'master'

Added minimal docs for new add, del and sync members commands.

See merge request !662
parents 522ecae8 156afb8d
Pipeline #155964009 passed with stage
in 10 minutes and 40 seconds
==============
Adding members
==============
The ``mailman addmembers`` command allows a site administrator to add members
to a mailing list.
>>> command = cli('mailman.commands.cli_addmembers.addmembers')
You can add members to a mailing list from the command line. To do so, you
need a file containing email addresses and optional display names that can be
parsed by ``email.utils.parseaddr()``.
::
>>> from tempfile import NamedTemporaryFile
>>> filename = cleanups.enter_context(NamedTemporaryFile()).name
>>> bee = create_list('[email protected]')
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... Bart Person <[email protected]>
... [email protected] (Cate Person)
... """, file=fp)
>>> command('mailman addmembers ' + filename + ' bee.example.com')
>>> from operator import attrgetter
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Bart Person <[email protected]>
Cate Person <[email protected]>
You can also specify ``-`` as the filename, in which case the addresses are
taken from standard input.
::
>>> stdin = """\
... [email protected]
... Elly Person <[email protected]>
... [email protected] (Fred Person)
... """
>>> command('mailman addmembers - bee.example.com', input=stdin)
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Bart Person <[email protected]>
Cate Person <[email protected]>
[email protected]
Elly Person <[email protected]>
Fred Person <[email protected]>
Blank lines and lines that begin with '#' are ignored.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... # [email protected]
...
... [email protected]
... """, file=fp)
>>> command('mailman addmembers ' + filename + ' bee.example.com')
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Bart Person <[email protected]>
Cate Person <[email protected]>
[email protected]
Elly Person <[email protected]>
Fred Person <[email protected]>
[email protected]
[email protected]
Addresses which are already subscribed are ignored, although a warning is
printed.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... [email protected]
... [email protected]
... """, file=fp)
>>> command('mailman addmembers ' + filename + ' bee.example.com')
Already subscribed (skipping): [email protected]
Already subscribed (skipping): [email protected]
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Bart Person <[email protected]>
Cate Person <[email protected]>
[email protected]
Elly Person <[email protected]>
Fred Person <[email protected]>
[email protected]
[email protected]
[email protected]
================
Managing members
================
The ``mailman members`` command allows a site administrator to display, add,
and delete members from a mailing list.
>>> command = cli('mailman.commands.cli_delmembers.delmembers')
You can delete members from a mailing list from the command line. To do so, you
need a file containing email addresses and optional display names that can be
parsed by ``email.utils.parseaddr()``. All mail addresses in the file will be
deleted from the mailing list. You can also specify members with command
options on the command line.
First we need a list with some members.
::
>>> bee = create_list('[email protected]')
>>> from mailman.testing.helpers import subscribe
>>> subscribe(bee, 'Anne')
<Member: Anne Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Bart')
<Member: Bart Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Cate')
<Member: Cate Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Doug')
<Member: Doug Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Elly')
<Member: Elly Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Fred')
<Member: Fred Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Greg')
<Member: Greg Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Irma')
<Member: Irma Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Jeff')
<Member: Jeff Person <[email protected]> on [email protected]
as MemberRole.member>
Now we can delete some members.
::
>>> from tempfile import NamedTemporaryFile
>>> filename = cleanups.enter_context(NamedTemporaryFile()).name
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... [email protected] (Cate Person)
... """, file=fp)
>>> command('mailman delmembers -f ' + filename + ' -l bee.example.com')
>>> from operator import attrgetter
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
Bart Person <[email protected]>
Doug Person <[email protected]>
Elly Person <[email protected]>
Fred Person <[email protected]>
Greg Person <[email protected]>
Irma Person <[email protected]>
Jeff Person <[email protected]>
You can also specify ``-`` as the filename, in which case the addresses are
taken from standard input.
::
>>> stdin = """\
... [email protected]
... Elly Person <[email protected]>
... """
>>> command('mailman delmembers -f - -l bee.example.com', input=stdin)
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
Bart Person <[email protected]>
Fred Person <[email protected]>
Greg Person <[email protected]>
Irma Person <[email protected]>
Jeff Person <[email protected]>
Blank lines and lines that begin with '#' are ignored.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... # [email protected]
...
... [email protected]
... """, file=fp)
>>> command('mailman delmembers -f ' + filename + ' -l bee.example.com')
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
Fred Person <[email protected]>
Greg Person <[email protected]>
Irma Person <[email protected]>
Jeff Person <[email protected]>
Addresses which are not subscribed are ignored, although a warning is
printed.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... [email protected]
... """, file=fp)
>>> command('mailman delmembers -f ' + filename + ' -l bee.example.com')
Member not subscribed (skipping): [email protected]
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
Fred Person <[email protected]>
Greg Person <[email protected]>
Jeff Person <[email protected]>
Addresses to delete can be specified on the command line.
::
>>> command('mailman delmembers -m [email protected] -l bee.example.com')
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
Fred Person <[email protected]>
Jeff Person <[email protected]>
All members can be deleted as well.
::
>>> command('mailman delmembers --all -l bee.example.com')
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
*Empty*
===============
Syncing members
===============
The ``mailman syncmembers`` command allows a site administrator to sync the
membership of a mailing list with an input file.
>>> command = cli('mailman.commands.cli_syncmembers.syncmembers')
You can synchronize all member addresses of a mailing list with the
member addresses found in a file from the command line. To do so, you
need a file containing email addresses and optional display names that can be
parsed by ``email.utils.parseaddr()``. All mail addresses *not contained* in
the file will be *deleted* from the mailing list. Every address *found* in the
specified file will be added to the specified mailing list.
First we create a list and add a few members.
::
>>> bee = create_list('[email protected]')
>>> from mailman.testing.helpers import subscribe
>>> subscribe(bee, 'Fred')
<Member: Fred Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Greg')
<Member: Greg Person <[email protected]> on [email protected]
as MemberRole.member>
>>> subscribe(bee, 'Jeff')
<Member: Jeff Person <[email protected]> on [email protected]
as MemberRole.member>
*Note* that only changes of the mailing list will be written to output so in
the first example, Fred is a member who remains on the list and isn't reported.
::
>>> from tempfile import NamedTemporaryFile
>>> filename = cleanups.enter_context(NamedTemporaryFile()).name
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... [email protected] (Cate Person)
... Fred Person <[email protected]>
... """, file=fp)
>>> command('mailman syncmembers ' + filename + ' bee.example.com')
[ADD] [email protected]
[ADD] Cate Person <[email protected]>
[DEL] Greg Person <[email protected]>
[DEL] Jeff Person <[email protected]>
>>> from operator import attrgetter
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Cate Person <[email protected]>
Fred Person <[email protected]>
You can also specify ``-`` as the filename, in which case the addresses are
taken from standard input.
::
>>> stdin = """\
... [email protected]
... Elly Person <[email protected]>
... """
>>> command('mailman syncmembers - bee.example.com', input=stdin)
[ADD] [email protected]
[ADD] Elly Person <[email protected]>
[DEL] [email protected]
[DEL] Cate Person <[email protected]>
[DEL] Fred Person <[email protected]>
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Elly Person <[email protected]>
Blank lines and lines that begin with '#' are ignored.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... #[email protected]
... [email protected]
...
... [email protected]
... """, file=fp)
>>> command('mailman syncmembers ' + filename + ' bee.example.com')
[ADD] [email protected]
[DEL] [email protected]
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Elly Person <[email protected]>
If there is nothing to do, it will output just that.
::
>>> with open(filename, 'w', encoding='utf-8') as fp:
... print("""\
... [email protected]
... [email protected]
... """, file=fp)
>>> command('mailman syncmembers ' + filename + ' bee.example.com')
Nothing to do
>>> dump_list(bee.members.addresses, key=attrgetter('email'))
[email protected]
Elly Person <[email protected]>
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment