src/mailman/interfaces/api.py

   1 # Copyright (C) 2016-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 """REST web service API context."""
  19
  20 from public import public
  21 from zope.interface import Attribute, Interface
  22
  23
  24 @public
  25 class IAPI(Interface):
  26     """The REST web service context."""
  27
  28     version = Attribute(
  29         """The REST API version as a string.""")
  30
  31     version_info = Attribute(
  32         """The REST API version as a tuple of integers.""")
  33
  34     def path_to(resource):
  35         """Return the full REST URL to the given resource.
  36
  37         :param resource: Resource path string without the leading scheme,
  38             host, port, or API version information.
  39         :type resource: str
  40         :return: Full URL path to the resource, with the scheme, host, port
  41             and API version prepended.
  42         :rtype: str
  43         """
  44
  45     def from_uuid(uuid):
  46         """Return the string representation of a UUID.
  47
  48         :param uuid: The UUID to convert.
  49         :type uuid: UUID
  50         :return: The string representation of the UUID, as appropriate for the
  51             API version.  In 3.0 this is the representation of an integer,
  52             while in 3.1 it is the hex representation.
  53         :rtype: str
  54         """
  55
  56     def to_uuid(uuid):
  57         """Return the UUID from the string representation.
  58
  59         :param uuid: A UUID, or the string representation of the UUID.
  60         :type uuid: UUID or str
  61         :return: The UUID, converted if needed as appropriate for the
  62             API version.  In 3.0, the string representation is
  63             interpreted as an integer, while in 3.1 it is the hex
  64             string.
  65         :rtype: UUID
  66         """