Merge ~cjwatson/lazr.restful:remove-class-advisors into lazr.restful:main

[Colin Watson]

Remove old class advisors

The deprecated `export_as_webservice_entry` and `export_as_webservice_collection` class advisors only worked on Python 2, and were already replaced by `@exported_as_webservice_entry` and `@exported_as_webservice_collection` for Python 3.

This doesn't require a new major version, because we declare `python_requires=">=3.5"` and so pip (>= 9, anyway) on Python 2 won't upgrade to this version.

[Jürgen Gmach (jugmac00)]

LGTM

> because we declare `python_requires=">=3.5"` and so pip on Python 2 won't upgrade to this version

pip >= 9 :-)

review: Approve

diff --git a/NEWS.rst b/NEWS.rst
index c9dff29..e2477fb 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -20,6 +20,11 @@ NEWS for lazr.restful
   => ``lazr.restful.testing.webservice.StubRootResourceURL``
 - Apply black code formatter via pre-commit.
 - Drop Python 2 support.
+- Remove ``export_as_webservice_entry`` and
+  ``export_as_webservice_collection``; these were deprecated in 0.22.0 and
+  cannot work on Python 3.  Use the class decorators
+  ``@exported_as_webservice_entry`` and
+  ``@exported_as_webservice_collection`` instead.
 
 1.1.0 (2021-10-07)
 ==================
diff --git a/src/lazr/restful/declarations.py b/src/lazr/restful/declarations.py
index f717592..886eedb 100644
--- a/src/lazr/restful/declarations.py
+++ b/src/lazr/restful/declarations.py
@@ -16,8 +16,6 @@ __all__ = [
     "call_with",
     "collection_default_content",
     "error_status",
-    "export_as_webservice_collection",
-    "export_as_webservice_entry",
     "export_destructor_operation",
     "export_factory_operation",
     "export_operation_as",
@@ -49,7 +47,6 @@ import sys
 import six
 from zope.component import getUtility, getGlobalSiteManager
 from zope.interface import classImplements
-from zope.interface.advice import addClassAdvisor
 from zope.interface.interface import fromFunction, InterfaceClass, TAGGED_DATA
 from zope.interface.interfaces import IInterface, IMethod
 from zope.schema import (
@@ -179,8 +176,7 @@ def _export_as_webservice_entry(
 ):
     """Tag an interface as exported on the web service as an entry.
 
-    This is the core of export_as_webservice_entry and
-    exported_as_webservice_entry.
+    This is the core of exported_as_webservice_entry.
     """
     annotation_stack = VersionedDict()
 
@@ -261,66 +257,6 @@ def _export_as_webservice_entry(
     annotate_exported_methods(interface)
 
 
-def export_as_webservice_entry(
-    singular_name=None,
-    plural_name=None,
-    contributes_to=None,
-    publish_web_link=True,
-    as_of=None,
-    versioned_annotations=None,
-):
-    """Mark the content interface as exported on the web service as an entry.
-
-    If contributes_to is a non-empty sequence of Interfaces, this entry will
-    actually not be exported on its own but instead will contribute its
-    attributes/methods to other exported entries.
-
-    This function does not work with Python 3.  Rather than calling this
-    within the class definition, decorate the class with
-    @exported_as_webservice_entry instead.
-
-    :param singular_name: The human-readable singular name of the entry,
-        eg. "paintbrush".
-    :param plural_name: The human-readable plural name of the entry,
-        eg. "paintbrushes"
-    :param contributes_to: An optional list of exported interfaces to which
-        this interface contributes.
-    :param publish_web_link: This parameter is ignored unless there is
-        a correspondence between this web service's entries and the
-        pages on some website. If that is so, and if this parameter is
-        set to True, the representation of this entry will include a
-        web_link pointing to the corresponding page on the website. If
-        False, web_link will be omitted.
-    :param as_of: The first version of the web service to feature this entry.
-    :param versioned_annotations: A list of 2-tuples (version,
-        {params}), with more recent web service versions earlier in
-        the list and older versions later in the list.
-
-        A 'params' dictionary may contain the key 'exported', which
-        controls whether or not to publish the entry at all in the
-        given version. It may also contain the keys 'singular_name',
-        'plural_name', 'contributes_to', or 'publish_web_link', which
-        work just like the corresponding arguments to this method.
-    """
-    _check_called_from_interface_def("export_as_webservice_entry()")
-
-    def mark_entry(interface):
-        """Class advisor that tags the interface once it is created."""
-        _check_interface("export_as_webservice_entry()", interface)
-        _export_as_webservice_entry(
-            interface,
-            singular_name=singular_name,
-            plural_name=plural_name,
-            contributes_to=contributes_to,
-            publish_web_link=publish_web_link,
-            as_of=as_of,
-            versioned_annotations=versioned_annotations,
-        )
-        return interface
-
-    addClassAdvisor(mark_entry)
-
-
 class exported_as_webservice_entry:
     """Mark the content interface as exported on the web service as an entry.
 
@@ -497,40 +433,6 @@ def _check_collection_default_content(name, interface):
         )
 
 
-def export_as_webservice_collection(entry_schema):
-    """Mark the interface as exported on the web service as a collection.
-
-    This function does not work with Python 3.  Rather than calling this
-    within the class definition, decorate the class with
-    @exported_as_webservice_collection instead.
-
-    :raises TypeError: if the interface doesn't have a method decorated with
-        @collection_default_content.
-    """
-    _check_called_from_interface_def("export_as_webservice_collection()")
-
-    if not IInterface.providedBy(entry_schema):
-        raise TypeError("entry_schema must be an interface.")
-
-    # Set the tags at this point, so that future declarations can
-    # check it.
-    tags = _get_interface_tags()
-    tags[LAZR_WEBSERVICE_EXPORTED] = dict(
-        type=COLLECTION_TYPE, collection_entry_schema=entry_schema
-    )
-
-    def mark_collection(interface):
-        """Class advisor that tags the interface once it is created."""
-        _check_interface("export_as_webservice_collection()", interface)
-        _check_collection_default_content(
-            "export_as_webservice_collection()", interface
-        )
-        annotate_exported_methods(interface)
-        return interface
-
-    addClassAdvisor(mark_collection)
-
-
 class exported_as_webservice_collection:
     """Mark the interface as exported on the web service as a collection.
 
@@ -580,14 +482,14 @@ class collection_default_content:
         # We used to check that this decorator is being used from within an
         # interface exported as a collection.  However, it isn't possible to
         # do this when using the @exported_as_webservice_collection
-        # decorator rather than the export_as_webservice_collection function
-        # (which is based on class advice, and so cannot work in Python 3):
-        # that decorator isn't called until the rest of the interface has
-        # been defined, so it hasn't had a chance to set any tags on the
-        # interface by the time decorators of methods in that interface are
-        # called.  The best we can do is to check that we don't already
-        # positively know that the interface is exported as an entry
-        # instead.
+        # decorator rather than the old export_as_webservice_collection
+        # function (which was based on class advice, and so cannot work in
+        # Python 3): that decorator isn't called until the rest of the
+        # interface has been defined, so it hasn't had a chance to set any
+        # tags on the interface by the time decorators of methods in that
+        # interface are called.  The best we can do is to check that we
+        # don't already positively know that the interface is exported as an
+        # entry instead.
         tags = _get_interface_tags()
         tag = tags.setdefault(LAZR_WEBSERVICE_EXPORTED, {})
         if "type" in tag and tag["type"] != COLLECTION_TYPE:
@@ -684,9 +586,7 @@ class _method_annotator:
 
     The actual method will be wrapped in an IMethod specification once the
     Interface is complete. So we save the annotations in an attribute of the
-    method, and either the class advisor invoked by
-    export_as_webservice_entry() and export_as_webservice_collection() or
-    the @exported_as_webservice_entry() and
+    method, and the @exported_as_webservice_entry() and
     @exported_as_webservice_collection() decorators will do the final
     tagging.
     """
@@ -729,8 +629,8 @@ class _method_annotator:
         :param f: the method being annotated.
         :param annotations: the dict containing the method annotations.
 
-        The annotations will copied to the lazr.webservice.exported tag
-        by a class advisor.
+        The annotations will be copied to the lazr.webservice.exported tag
+        by a class decorator.
         """
         raise NotImplementedError
 
diff --git a/src/lazr/restful/tests/test_declarations.py b/src/lazr/restful/tests/test_declarations.py
index 305709b..6a2313b 100644
--- a/src/lazr/restful/tests/test_declarations.py
+++ b/src/lazr/restful/tests/test_declarations.py
@@ -2,8 +2,6 @@
 
 """Unit tests for the conversion of interfaces into a web service."""
 
-import sys
-
 import testtools
 from zope.component import (
     adapter,
@@ -35,17 +33,13 @@ from zope.security.management import (
 from lazr.restful.declarations import (
     accessor_for,
     call_with,
-    collection_default_content,
     error_status,
-    export_as_webservice_collection,
-    export_as_webservice_entry,
     export_read_operation,
     export_write_operation,
     exported,
     exported_as_webservice_entry,
     generate_entry_interfaces,
     generate_operation_adapter,
-    LAZR_WEBSERVICE_EXPORTED,
     LAZR_WEBSERVICE_NAME,
     mutator_for,
     operation_for_version,
@@ -430,165 +424,6 @@ class ContributingInterfacesTestCase(TestCaseWithWebServiceFixtures):
         )
 
 
-class TestExportAsWebserviceEntry(testtools.TestCase):
-    """Tests for export_as_webservice_entry."""
-
-    def setUp(self):
-        super().setUp()
-        if sys.version_info[0] >= 3:
-            self.skipTest(
-                "export_as_webservice_entry is only supported on Python 2"
-            )
-
-    def test_works_on_interface(self):
-        # export_as_webservice_entry works on an interface.
-        class IFoo(Interface):
-            export_as_webservice_entry()
-
-        self.assertTrue(
-            IFoo.queryTaggedValue(LAZR_WEBSERVICE_EXPORTED)["exported"]
-        )
-
-    def test_requires_interface(self):
-        # export_as_webservice_entry can only be used on Interface.
-        def export_non_interface():
-            class NotAnInterface:
-                export_as_webservice_entry()
-
-        exception = self.assertRaises(TypeError, export_non_interface)
-        self.assertEqual(
-            "export_as_webservice_entry() can only be used on an interface.",
-            str(exception),
-        )
-
-    def test_must_be_within_interface_definition(self):
-        # export_as_webservice_entry can only be used from within a
-        # interface definition.
-        exception = self.assertRaises(TypeError, export_as_webservice_entry)
-        self.assertEqual(
-            "export_as_webservice_entry() can only be used from within an "
-            "interface definition.",
-            str(exception),
-        )
-
-
-class TestExportAsWebserviceCollection(testtools.TestCase):
-    """Tests for export_as_webservice_collection."""
-
-    def setUp(self):
-        super().setUp()
-        if sys.version_info[0] >= 3:
-            self.skipTest(
-                "export_as_webservice_collection is only supported on "
-                "Python 2"
-            )
-
-    def test_works_on_interface_with_tagged_method(self):
-        # export_as_webservice_collection works on an interface that has an
-        # entry schema and a method tagged with @collection_default_content.
-        class IFoo(Interface):
-            export_as_webservice_collection(Interface)
-
-            @collection_default_content()
-            def getAll():
-                pass
-
-        self.assertEqual(
-            {None: ("getAll", {})},
-            IFoo.queryTaggedValue(LAZR_WEBSERVICE_EXPORTED)[
-                "collection_default_content"
-            ],
-        )
-
-    def test_requires_entry_schema(self):
-        # export_as_webservice_collection requires an entry schema.
-        def export_without_entry_schema():
-            class MissingEntrySchema(Interface):
-                export_as_webservice_collection()
-
-        exception = self.assertRaises(TypeError, export_without_entry_schema)
-        self.assertEqual(
-            "export_as_webservice_collection() takes exactly 1 argument (0 "
-            "given)",
-            str(exception),
-        )
-
-    def test_requires_entry_schema_as_interface(self):
-        # export_as_webservice_collection requires the entry schema to be an
-        # interface.
-        def export_with_invalid_entry_schema():
-            class InvalidEntrySchema(Interface):
-                export_as_webservice_collection("not an interface")
-
-        exception = self.assertRaises(
-            TypeError, export_with_invalid_entry_schema
-        )
-        self.assertEqual("entry_schema must be an interface.", str(exception))
-
-    def test_requires_tagged_method(self):
-        # export_as_webservice_collection can only be used on a collection
-        # that has a method marked as exporting the default content.
-        def export_missing_default_content():
-            class MissingDefaultContent(Interface):
-                export_as_webservice_collection(Interface)
-
-        exception = self.assertRaises(
-            TypeError, export_missing_default_content
-        )
-        self.assertEqual(
-            "export_as_webservice_collection() is missing a method tagged "
-            "with @collection_default_content.",
-            str(exception),
-        )
-
-    def test_refuses_multiple_tagged_methods(self):
-        # export_as_webservice_collection cannot be used on a collection
-        # that has multiple methods marked as exporting the default content.
-        def export_two_default_content():
-            class TwoDefaultContent(Interface):
-                export_as_webservice_collection(Interface)
-
-                @collection_default_content()
-                def getAll1():
-                    """A first getAll()."""
-
-                @collection_default_content()
-                def getAll2():
-                    """Another getAll()."""
-
-        exception = self.assertRaises(TypeError, export_two_default_content)
-        self.assertEqual(
-            "Only one method can be marked with @collection_default_content "
-            "for version '(earliest version)'.",
-            str(exception),
-        )
-
-    def test_requires_interface(self):
-        # export_as_webservice_collection can only be used on Interface.
-        def export_non_interface():
-            class NotAnInterface:
-                export_as_webservice_collection(Interface)
-
-        exception = self.assertRaises(TypeError, export_non_interface)
-        self.assertEqual(
-            "export_as_webservice_collection() can only be used on an "
-            "interface.",
-            str(exception),
-        )
-
-    def test_must_be_within_interface_definition(self):
-        # export_as_webservice_collection can only be used from within an
-        # interface definition.
-        exception = self.assertRaises(
-            TypeError, export_as_webservice_collection, Interface
-        )
-        self.assertEqual(
-            "export_as_webservice_collection() can only be used from within "
-            "an interface definition.",
-            str(exception),
-        )
-
-
 class NotExportedException(Exception):
     pass