================
Managing members
================

The ``mailman members`` command allows a site administrator to display, add,
and remove members from a mailing list.

    >>> command = cli('mailman.commands.cli_members.members')


Listing members
===============

You can list all the members of a mailing list by calling the command with no
options.  To start with, there are no members of the mailing list.

    >>> ant = create_list('ant@example.com')
    >>> command('mailman members ant.example.com')
    ant.example.com has no members

Once the mailing list add some members, they will be displayed.
::

    >>> from mailman.testing.helpers import subscribe
    >>> subscribe(ant, 'Anne', email='anne@example.com')
    <Member: Anne Person <anne@example.com> on ant@example.com
             as MemberRole.member>
    >>> subscribe(ant, 'Bart', email='bart@example.com')
    <Member: Bart Person <bart@example.com> on ant@example.com
             as MemberRole.member>

    >>> command('mailman members ant.example.com')
    Anne Person <anne@example.com>
    Bart Person <bart@example.com>

Members are displayed in alphabetical order based on their address.
::

    >>> subscribe(ant, 'Anne', email='anne@aaaxample.com')
    <Member: Anne Person <anne@aaaxample.com> on ant@example.com
             as MemberRole.member>

    >>> command('mailman members ant.example.com')
    Anne Person <anne@aaaxample.com>
    Anne Person <anne@example.com>
    Bart Person <bart@example.com>

You can also output this list to a file.
::

    >>> from tempfile import NamedTemporaryFile
    >>> filename = cleanups.enter_context(NamedTemporaryFile()).name

    >>> command('mailman members -o ' + filename + ' ant.example.com')
    >>> with open(filename, 'r', encoding='utf-8') as fp:
    ...     print(fp.read())
    Anne Person <anne@aaaxample.com>
    Anne Person <anne@example.com>
    Bart Person <bart@example.com>

The output file can also be standard out.

    >>> command('mailman members -o - ant.example.com')
    Anne Person <anne@aaaxample.com>
    Anne Person <anne@example.com>
    Bart Person <bart@example.com>


Filtering on delivery mode
--------------------------

You can limit output to just the regular non-digest members...
::

    >>> member = ant.members.get_member('anne@example.com')
    >>> from mailman.interfaces.member import DeliveryMode
    >>> member.preferences.delivery_mode = DeliveryMode.plaintext_digests

    >>> command('mailman members --regular ant.example.com')
    Anne Person <anne@aaaxample.com>
    Bart Person <bart@example.com>

...or just the digest members.  Furthermore, you can either display all digest
members...
::

    >>> member = ant.members.get_member('anne@aaaxample.com')
    >>> member.preferences.delivery_mode = DeliveryMode.mime_digests

    >>> command('mailman members --digest any ant.example.com')
    Anne Person <anne@aaaxample.com>
    Anne Person <anne@example.com>

...just plain text digest members...

    >>> command('mailman members --digest plaintext ant.example.com')
    Anne Person <anne@example.com>

...or just MIME digest members.
::

    >>> command('mailman members --digest mime ant.example.com')
    Anne Person <anne@aaaxample.com>


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 = ant.members.get_member('anne@aaaxample.com')
    >>> member.preferences.delivery_status = DeliveryStatus.by_moderator
    >>> member = ant.members.get_member('bart@example.com')
    >>> member.preferences.delivery_status = DeliveryStatus.by_user

    >>> member = subscribe(ant, 'Cris', email='cris@example.com')
    >>> member.preferences.delivery_status = DeliveryStatus.unknown
    >>> member = subscribe(ant, 'Dave', email='dave@example.com')
    >>> member.preferences.delivery_status = DeliveryStatus.enabled
    >>> member = subscribe(ant, 'Elle', email='elle@example.com')
    >>> member.preferences.delivery_status = DeliveryStatus.by_bounces

    >>> command('mailman members --nomail enabled ant.example.com')
    Anne Person <anne@example.com>
    Dave Person <dave@example.com>

...or disabled by the user...

    >>> command('mailman members --nomail byuser ant.example.com')
    Bart Person <bart@example.com>

...or disabled by the list administrator (or moderator)...

    >>> command('mailman members --nomail byadmin ant.example.com')
    Anne Person <anne@aaaxample.com>

...or by the bounce processor...

    >>> command('mailman members --nomail bybounces ant.example.com')
    Elle Person <elle@example.com>

...or for unknown (legacy) reasons.

    >>> command('mailman members --nomail unknown ant.example.com')
    Cris Person <cris@example.com>

You can also display all members who have delivery disabled for any reason.
::

    >>> command('mailman members --nomail any ant.example.com')
    Anne Person <anne@aaaxample.com>
    Bart Person <bart@example.com>
    Cris Person <cris@example.com>
    Elle Person <elle@example.com>


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()``.
::

    >>> bee = create_list('bee@example.com')
    >>> with open(filename, 'w', encoding='utf-8') as fp:
    ...     print("""\
    ... aperson@example.com
    ... Bart Person <bperson@example.com>
    ... cperson@example.com (Cate Person)
    ... """, file=fp)

    >>> command('mailman members --add ' + filename + ' bee.example.com')

    >>> from operator import attrgetter
    >>> dump_list(bee.members.addresses, key=attrgetter('email'))
    aperson@example.com
    Bart Person <bperson@example.com>
    Cate Person <cperson@example.com>

You can also specify ``-`` as the filename, in which case the addresses are
taken from standard input.
::

    >>> stdin = """\
    ... dperson@example.com
    ... Elly Person <eperson@example.com>
    ... fperson@example.com (Fred Person)
    ... """
    >>> command('mailman members --add - bee.example.com', input=stdin)

    >>> dump_list(bee.members.addresses, key=attrgetter('email'))
    aperson@example.com
    Bart Person <bperson@example.com>
    Cate Person <cperson@example.com>
    dperson@example.com
    Elly Person <eperson@example.com>
    Fred Person <fperson@example.com>

Blank lines and lines that begin with '#' are ignored.
::

    >>> with open(filename, 'w', encoding='utf-8') as fp:
    ...     print("""\
    ... gperson@example.com
    ... # hperson@example.com
    ...
    ... iperson@example.com
    ... """, file=fp)

    >>> command('mailman members --add ' + filename + ' bee.example.com')

    >>> dump_list(bee.members.addresses, key=attrgetter('email'))
    aperson@example.com
    Bart Person <bperson@example.com>
    Cate Person <cperson@example.com>
    dperson@example.com
    Elly Person <eperson@example.com>
    Fred Person <fperson@example.com>
    gperson@example.com
    iperson@example.com

Addresses which are already subscribed are ignored, although a warning is
printed.
::

    >>> with open(filename, 'w', encoding='utf-8') as fp:
    ...     print("""\
    ... gperson@example.com
    ... aperson@example.com
    ... jperson@example.com
    ... """, file=fp)

    >>> command('mailman members --add ' + filename + ' bee.example.com')
    Already subscribed (skipping): gperson@example.com
    Already subscribed (skipping): aperson@example.com

    >>> dump_list(bee.members.addresses, key=attrgetter('email'))
    aperson@example.com
    Bart Person <bperson@example.com>
    Cate Person <cperson@example.com>
    dperson@example.com
    Elly Person <eperson@example.com>
    Fred Person <fperson@example.com>
    gperson@example.com
    iperson@example.com
    jperson@example.com


Displaying members
==================

With no arguments, the command displays all members of the list.

    >>> command('mailman members bee.example.com')
    aperson@example.com
    Bart Person <bperson@example.com>
    Cate Person <cperson@example.com>
    dperson@example.com
    Elly Person <eperson@example.com>
    Fred Person <fperson@example.com>
    gperson@example.com
    iperson@example.com
    jperson@example.com