src/mailman/commands/cli_members.py

   1 # Copyright (C) 2009-2022 by the Free Software Foundation, Inc.
   2 #
   3 # This file is part of GNU Mailman.
   4 #
   5 # GNU Mailman is free software: you can redistribute it and/or modify it under
   6 # the terms of the GNU General Public License as published by the Free
   7 # Software Foundation, either version 3 of the License, or (at your option)
   8 # any later version.
   9 #
  10 # GNU Mailman is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  13 # more details.
  14 #
  15 # You should have received a copy of the GNU General Public License along with
  16 # GNU Mailman.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 """The 'members' subcommand."""
  19
  20 import click
  21
  22 from mailman.core.i18n import _
  23 from mailman.interfaces.command import ICLISubCommand
  24 from mailman.interfaces.listmanager import IListManager
  25 from mailman.interfaces.member import DeliveryMode, DeliveryStatus, MemberRole
  26 from mailman.utilities.options import I18nCommand
  27 from operator import attrgetter
  28 from public import public
  29 from zope.component import getUtility
  30 from zope.interface import implementer
  31
  32
  33 def display_members(ctx, mlist, role, regular, digest,
  34                     nomail, outfp, email_only, count_only):
  35     # Which type of digest recipients should we display?
  36     if digest == 'any':
  37         digest_types = [
  38             DeliveryMode.plaintext_digests,
  39             DeliveryMode.mime_digests,
  40             DeliveryMode.summary_digests,
  41             ]
  42     elif digest == 'mime':
  43         # Include summary with mime as they are currently treated alike.
  44         digest_types = [
  45             DeliveryMode.mime_digests,
  46             DeliveryMode.summary_digests,
  47             ]
  48     elif digest is not None:
  49         digest_types = [DeliveryMode[digest + '_digests']]
  50     else:
  51         # Don't filter on digest type.
  52         pass
  53     # Which members with delivery disabled should we display?
  54     if nomail is None:
  55         # Don't filter on delivery status.
  56         pass
  57     elif nomail == 'byadmin':
  58         status_types = [DeliveryStatus.by_moderator]
  59     elif nomail.startswith('by'):
  60         status_types = [DeliveryStatus['by_' + nomail[2:]]]
  61     elif nomail == 'enabled':
  62         status_types = [DeliveryStatus.enabled]
  63     elif nomail == 'unknown':
  64         status_types = [DeliveryStatus.unknown]
  65     elif nomail == 'any':
  66         status_types = [
  67             DeliveryStatus.by_user,
  68             DeliveryStatus.by_bounces,
  69             DeliveryStatus.by_moderator,
  70             DeliveryStatus.unknown,
  71             ]
  72     else:                                           # pragma: nocover
  73         # click should enforce a valid nomail option.
  74         raise AssertionError(nomail)
  75     # Which roles should we display?
  76     if role is None:
  77         # By default, filter on members.
  78         roster = mlist.members
  79     elif role == 'administrator':
  80         roster = mlist.administrators
  81     elif role == 'any':
  82         roster = mlist.subscribers
  83     else:
  84         # click should enforce a valid member role.
  85         roster = mlist.get_roster(MemberRole[role])
  86     # Print; outfp will be either the file or stdout to print to.
  87     addresses = list(roster.addresses)
  88     if len(addresses) == 0:
  89         print(0 if count_only else _('${mlist.list_id} has no members'),
  90               file=outfp)
  91         return
  92     if count_only:
  93         print(roster.member_count, file=outfp)
  94         return
  95     for address in sorted(addresses, key=attrgetter('email')):
  96         member = roster.get_member(address.email)
  97         if regular:
  98             if member.delivery_mode != DeliveryMode.regular:
  99                 continue
 100         if digest is not None:
 101             if member.delivery_mode not in digest_types:
 102                 continue
 103         if nomail is not None:
 104             if member.delivery_status not in status_types:
 105                 continue
 106         if email_only or not address.display_name:
 107             print(address.original_email, file=outfp)
 108         else:
 109             print(f'{address.display_name} <{address.original_email}>',
 110                   file=outfp)
 111
 112
 113 @click.command(
 114     cls=I18nCommand,
 115     help=_("""\
 116     Display a mailing list's members.
 117     Filtering along various criteria can be done when displaying.
 118     With no options given, displaying mailing list members
 119     to stdout is the default mode.
 120     """))
 121 @click.option(
 122     '--add', '-a', 'add_infp', metavar='FILENAME',
 123     type=click.File(encoding='utf-8'),
 124     help=_("""\
 125     [MODE] Add all member addresses in FILENAME.  This option is removed.
 126     Use 'mailman addmembers' instead."""))
 127 @click.option(
 128     '--delete', '-x', 'del_infp', metavar='FILENAME',
 129     type=click.File(encoding='utf-8'),
 130     help=_("""\
 131     [MODE] Delete all member addresses found in FILENAME.
 132     This option is removed. Use 'mailman delmembers' instead."""))
 133 @click.option(
 134     '--sync', '-s', 'sync_infp', metavar='FILENAME',
 135     type=click.File(encoding='utf-8'),
 136     help=_("""\
 137     [MODE] Synchronize all member addresses of the specified mailing list
 138     with the member addresses found in FILENAME.
 139     This option is removed. Use 'mailman syncmembers' instead."""))
 140 @click.option(
 141     '--output', '-o', 'outfp', metavar='FILENAME',
 142     type=click.File(mode='w', encoding='utf-8', atomic=True),
 143     help=_("""\
 144     Display output to FILENAME instead of stdout.  FILENAME
 145     can be '-' to indicate standard output."""))
 146 @click.option(
 147     '--role', '-R',
 148     type=click.Choice(('any', 'owner', 'moderator', 'nonmember', 'member',
 149                        'administrator')),
 150     help=_("""\
 151     Display only members with a given ROLE.
 152     The role may be 'any', 'member', 'nonmember', 'owner', 'moderator',
 153     or 'administrator' (i.e. owners and moderators).
 154     If not given, then 'member' role is assumed."""))
 155 @click.option(
 156     '--regular', '-r',
 157     is_flag=True, default=False,
 158     help=_("""\
 159     Display only regular delivery members."""))
 160 @click.option(
 161     '--email-only', '-e', 'email_only',
 162     is_flag=True, default=False,
 163     help=("""\
 164     Display member addresses only, without the display name.
 165     """))
 166 @click.option(
 167     '--count-only', '-c', 'count_only',
 168     is_flag=True, default=False,
 169     help=("""\
 170     Display members count only.
 171     """))
 172 @click.option(
 173     '--no-change', '-N', 'no_change',
 174     is_flag=True, default=False,
 175     help=_("""\
 176     This option has no effect. It exists for backwards compatibility only."""))
 177 @click.option(
 178     '--digest', '-d', metavar='kind',
 179     # baw 2010-01-23 summary digests are not really supported yet.
 180     type=click.Choice(('any', 'plaintext', 'mime')),
 181     help=_("""\
 182     Display only digest members of kind.
 183     'any' means any digest type, 'plaintext' means only plain text (rfc 1153)
 184     type digests, 'mime' means MIME type digests."""))
 185 @click.option(
 186     '--nomail', '-n', metavar='WHY',
 187     type=click.Choice(('enabled', 'any', 'unknown',
 188                        'byadmin', 'byuser', 'bybounces')),
 189     help=_("""\
 190     Display only members with a given delivery status.
 191     'enabled' means all members whose delivery is enabled, 'any' means
 192     members whose delivery is disabled for any reason, 'byuser' means
 193     that the member disabled their own delivery, 'bybounces' means that
 194     delivery was disabled by the automated bounce processor,
 195     'byadmin' means delivery was disabled by the list
 196     administrator or moderator, and 'unknown' means that delivery was disabled
 197     for unknown (legacy) reasons."""))
 198 @click.argument('listspec')
 199 @click.pass_context
 200 def members(ctx, add_infp, del_infp, sync_infp, outfp,
 201             role, regular, no_change, digest, nomail, listspec,
 202             email_only, count_only):
 203     mlist = getUtility(IListManager).get(listspec)
 204     if mlist is None:
 205         ctx.fail(_('No such list: ${listspec}'))
 206     if add_infp is not None:
 207         ctx.fail('The --add option is removed. '
 208                  'Use `mailman addmembers` instead.')
 209     elif del_infp is not None:
 210         ctx.fail('The --delete option is removed. '
 211                  'Use `mailman delmembers` instead.')
 212     elif sync_infp is not None:
 213         ctx.fail('The --sync option is removed. '
 214                  'Use `mailman syncmembers` instead.')
 215     elif role == 'any' and (regular or digest or nomail):
 216         ctx.fail('The --regular, --digest and --nomail options are '
 217                  'incompatible with role=any.')
 218     elif email_only and count_only:
 219         ctx.fail('The --email_only and --count_only options are '
 220                  'mutually exclusive.')
 221     else:
 222         display_members(ctx, mlist, role, regular,
 223                         digest, nomail, outfp, email_only, count_only)
 224
 225
 226 @public
 227 @implementer(ICLISubCommand)
 228 class Members:
 229     name = 'members'
 230     command = members