src/mailman/interfaces/command.py

   1 # Copyright (C) 2008-2023 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 """Interfaces defining email commands."""
  19
  20 from enum import Enum
  21 from public import public
  22 from zope.interface import Attribute, Interface
  23
  24
  25 @public
  26 class ContinueProcessing(Enum):
  27     """Should `IEmailCommand.process()` continue or not."""
  28     no = 0
  29     yes = 1
  30
  31
  32 @public
  33 class IEmailResults(Interface):
  34     """The email command results object."""
  35
  36     output = Attribute('An output file object for printing results to.')
  37
  38
  39 @public
  40 class IEmailCommand(Interface):
  41     """An email command."""
  42
  43     name = Attribute('Command name as seen in a -request email.')
  44
  45     argument_description = Attribute('Description of command arguments.')
  46
  47     description = Attribute('Command help.')
  48
  49     def process(mlist, msg, msgdata, arguments, results):
  50         """Process the email command.
  51
  52         :param mlist: The mailing list target of the command.
  53         :param msg: The original message object.
  54         :param msgdata: The message metadata.
  55         :param arguments: The command arguments tuple.
  56         :param results: An IEmailResults object for these commands.
  57         :return: A `ContinueProcessing` enum specifying whether to continue
  58             processing or not.
  59         """
  60
  61
  62 @public
  63 class ICLISubCommand(Interface):
  64     """A command line interface subcommand.
  65
  66     Subcommands are implemented using the `click` package.  See
  67     https://click.palletsprojects.com/en/7.x/ for details.
  68     """
  69     name = Attribute(
  70         """The subcommand name as it will show up in `mailman --help`.
  71
  72         This must be unique; it is a runtime error if any plugin provides a
  73         subcommand with a clashing name.
  74         """)
  75
  76     command = Attribute(
  77         """The click command to run for this subcommand.
  78
  79         This must be a function decorated with at least the @click.command()
  80         decorator.  The function may also be decorated with other arguments as
  81         needed.
  82         """)