findmember.rst 5.86 KB
Newer Older
Mark Sapiro's avatar
Mark Sapiro committed
1 2 3 4
===============
Finding members
===============

5 6
The ``mailman findmember`` command reports all members with email address
matching a case-insensitive supplied pattern by address, list and role.
Mark Sapiro's avatar
Mark Sapiro committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83

    >>> from mailman.testing.documentation import cli
    >>> command = cli('mailman.commands.cli_findmember.findmember')

Usage
-----

Here is the complete usage for the command.
::

    >>> command('mailman findmember --help')
    Usage: findmember [OPTIONS] PATTERN
    <BLANKLINE>
      Display all memberships for a user or users with address matching a pattern.
    <BLANKLINE>
    Options:
      -r, --role [all|owner|moderator|nonmember|member|administrator]
                                      Display only memberships with the given role.
                                      If not given, 'all' role, i.e. all roles, is
                                      the default.
    <BLANKLINE>
      --help                          Show this message and exit.

Examples
--------

You can find all memberships for an address.

First we create some lists and add a few members as users or addresses and
with various roles.
::

    >>> from mailman.app.lifecycle import create_list
    >>> ant = create_list('ant@example.com')
    >>> bee = create_list('bee@example.com')
    >>> from mailman.interfaces.member import MemberRole
    >>> from mailman.testing.helpers import subscribe
    >>> subscribe(ant, 'Anne')
    <Member: Anne Person <aperson@example.com> on ant@example.com
             as MemberRole.member>
    >>> subscribe(ant, 'Bart', as_user=True)
    <Member: Bart Person <bperson@example.com> on ant@example.com
             as MemberRole.member>
    >>> subscribe(ant, 'Cate', role=MemberRole.owner)
    <Member: Cate Person <cperson@example.com> on ant@example.com
             as MemberRole.owner>
    >>> subscribe(ant, 'Doug', role=MemberRole.moderator)
    <Member: Doug Person <dperson@example.com> on ant@example.com
             as MemberRole.moderator>
    >>> subscribe(ant, 'Elly', role=MemberRole.nonmember)
    <Member: Elly Person <eperson@example.com> on ant@example.com
             as MemberRole.nonmember>
    >>> subscribe(ant, 'Fred', role=MemberRole.nonmember, as_user=True)
    <Member: Fred Person <fperson@example.com> on ant@example.com
             as MemberRole.nonmember>
    >>> subscribe(bee, 'Bart')
    <Member: Bart Person <bperson@example.com> on bee@example.com
             as MemberRole.member>
    >>> subscribe(bee, 'Cate', role=MemberRole.moderator)
    <Member: Cate Person <cperson@example.com> on bee@example.com
             as MemberRole.moderator>
    >>> subscribe(bee, 'Doug', role=MemberRole.owner)
    <Member: Doug Person <dperson@example.com> on bee@example.com
             as MemberRole.owner>
    >>> subscribe(bee, 'Elly', role=MemberRole.owner)
    <Member: Elly Person <eperson@example.com> on bee@example.com
             as MemberRole.owner>
    >>> subscribe(bee, 'Fred', role=MemberRole.nonmember, as_user=True)
    <Member: Fred Person <fperson@example.com> on bee@example.com
             as MemberRole.nonmember>
    >>> subscribe(bee, 'Greg', as_user=True)
    <Member: Greg Person <gperson@example.com> on bee@example.com
             as MemberRole.member>
    >>> subscribe(bee, 'Jeff')
    <Member: Jeff Person <jperson@example.com> on bee@example.com
             as MemberRole.member>

Mark Sapiro's avatar
Mark Sapiro committed
84 85
First, use a pattern of ``person`` and no ``--role`` option to get all members
and roles.
Mark Sapiro's avatar
Mark Sapiro committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
::

    >>> command('mailman findmember person')
    Email: aperson@example.com
        List: ant.example.com
            MemberRole.member
    Email: bperson@example.com
        List: ant.example.com
            MemberRole.member
        List: bee.example.com
            MemberRole.member
    Email: cperson@example.com
        List: ant.example.com
            MemberRole.owner
        List: bee.example.com
            MemberRole.moderator
    Email: dperson@example.com
        List: ant.example.com
            MemberRole.moderator
        List: bee.example.com
            MemberRole.owner
    Email: eperson@example.com
        List: ant.example.com
            MemberRole.nonmember
        List: bee.example.com
            MemberRole.owner
    Email: fperson@example.com
        List: ant.example.com
            MemberRole.nonmember
        List: bee.example.com
            MemberRole.nonmember
    Email: gperson@example.com
        List: bee.example.com
            MemberRole.member
    Email: jperson@example.com
        List: bee.example.com
            MemberRole.member

We can use a more specific pattern to get just one email address.
::

    >>> command('mailman findmember bperson@example.com')
    Email: bperson@example.com
        List: ant.example.com
            MemberRole.member
        List: bee.example.com
            MemberRole.member

Patterns are matched case insensitively.
::

    >>> command('mailman findmember BPerson@example.com')
    Email: bperson@example.com
        List: ant.example.com
            MemberRole.member
        List: bee.example.com
            MemberRole.member

We can select only specific roles.  Here we get all owners.
::

    >>> command('mailman findmember --role owner .')
    Email: cperson@example.com
        List: ant.example.com
            MemberRole.owner
    Email: dperson@example.com
        List: bee.example.com
            MemberRole.owner
    Email: eperson@example.com
        List: bee.example.com
            MemberRole.owner

We can use the administrator role to get owners and moderators.
::

    >>> command('mailman findmember --role administrator .')
    Email: cperson@example.com
        List: ant.example.com
            MemberRole.owner
        List: bee.example.com
            MemberRole.moderator
    Email: dperson@example.com
        List: ant.example.com
            MemberRole.moderator
        List: bee.example.com
            MemberRole.owner
    Email: eperson@example.com
        List: bee.example.com
            MemberRole.owner