Apply suggestions from code review

These are mostly documentation changes. Some of the docstrings might influence the public availability of the methods on an object.

Co-authored-by: Michael Howitz <[email protected]>

.github/workflows/pre-commit.yml

@@ -1,3 +1,5 @@
+name: pre-commit
+
 on:
   pull_request:
 

src/OFS/DTMLDocument.py

@@ -46,10 +46,7 @@ class DTMLDocument(PropertyManager, DTMLMethod):
 
     # Replace change_dtml_methods by change_dtml_documents
     __ac_permissions__ = tuple([
-        # fmt: off
-        (perms[0] == change_dtml_methods) and  # NOQA: W504
-        (change_dtml_documents, perms[1]) or perms
-        # fmt: on
+        (change_dtml_documents, perms[1]) if (perms[0] == change_dtml_methods) else perms
         for perms in DTMLMethod.__ac_permissions__])
 
     def __call__(self, client=None, REQUEST={}, RESPONSE=None, **kw):

src/OFS/EtagSupport.py

@@ -20,10 +20,10 @@
 
 
 class EtagBaseInterface(Interface):
-    """\\ Basic Etag support interface, meaning the object supports generating
+    """Basic Etag support interface, meaning the object supports generating
     an Etag that can be used by certain HTTP and WebDAV Requests."""
     def http__etag():
-        """\\ Entity tags are used for comparing two or more entities from the
+        """Entity tags are used for comparing two or more entities from the
         same requested resource.
 
         Predominantly used for Caching, Etags can also be used to deal

src/OFS/Image.py

@@ -1083,7 +1083,9 @@ def tag(
         intelligently for 'height', 'width', and 'alt'. If specified,
         the 'scale', 'xscale', and 'yscale' keyword arguments will be
         used to automatically adjust the output height and width values
-        of the image tag. # Since 'class' is a Python reserved word, it
+        of the image tag.
+        
+        Since 'class' is a Python reserved word, it
         cannot be passed in directly in keyword arguments which is a
         problem if you are trying to use 'tag()' to include a CSS class.
         The tag() method will accept a 'css_class' argument that will be

src/OFS/PropertySheets.py

@@ -470,7 +470,6 @@ def get(self, name, default=None):
 
     @security.protected(manage_properties)
     def manage_addPropertySheet(self, id, ns, REQUEST=None):
-        """"""
         md = {'xmlns': ns}
         ps = self.PropertySheetClass(id, md)
         self.addPropertySheet(ps)

src/OFS/SimpleItem.py

@@ -303,7 +303,7 @@ def raise_standardErrorMessage(
             tb = None
 
     def manage(self, URL1):
-        """"""
+        """Redirect to manage_main."""
         raise Redirect("%s/manage_main" % URL1)
 
     # This keeps simple items from acquiring their parents

src/OFS/interfaces.py

@@ -394,7 +394,7 @@ class ILockItem(Interface):
     # XXX:  WAAAA!  What is a ctor doing in the interface?
     def __init__(creator, owner, depth=0, timeout='Infinity',
                  locktype='write', lockscope='exclusive', token=None):
-        """\\ If any of the  following are untrue, a **ValueError** exception
+        """If any of the  following are untrue, a **ValueError** exception
         will be raised.
 
          - **creator** MUST be a Zope user object or string to find a

src/OFS/tests/testFindSupport.py

@@ -4,7 +4,6 @@
 
 
 class DummyItem(FindSupport):
-    """"""
 
     def __init__(self, id, text=''):
         self.id = id

src/OFS/userfolder.py

@@ -112,7 +112,7 @@ def manage_userFolderProperties(
         REQUEST=None,
         manage_tabs_message=None
     ):
-        """"""
+        """Manage user folder properties."""
         return self._userFolderProperties(
             self,
             REQUEST,
@@ -321,7 +321,7 @@ def _createInitialUser(self):
 
 
 def manage_addUserFolder(self, dtself=None, REQUEST=None, **ignored):
-    """"""
+    """Add a user folder."""
     f = UserFolder()
     self = self.this()
     try:

src/Products/Five/browser/tests/test_defaultview.py

@@ -88,7 +88,7 @@ def test_default_view():
 
 
 def test_default_method_args_marshalling():
-    """\\ Test the default call method of a view, with respect to possible
+    """Test the default call method of a view, with respect to possible
     breakage of argument marshalling from other components.
 
     This is not directly a bug in Five, just a change that enables

src/Products/SiteAccess/VirtualHostMonster.py

@@ -254,7 +254,7 @@ def __bobo_traverse__(self, request, name):
 
 
 def manage_addVirtualHostMonster(self, id=None, REQUEST=None, **ignored):
-    """"""
+    """Add a virtual host monster."""
     container = self.this()
     vhm = VirtualHostMonster()
     container._setObject(vhm.getId(), vhm)

src/Shared/DC/Scripts/Signature.py

@@ -32,18 +32,14 @@ def __init__(self, varnames=(), argcount=-1):
     def __eq__(self, other):
         if not isinstance(other, FuncCode):
             return False
-        # fmt: off
-        return ((self.co_argcount, self.co_varnames) ==  # NOQA: W504
+        return ((self.co_argcount, self.co_varnames) ==
                 (other.co_argcount, other.co_varnames))
-        # fmt: on
 
     def __lt__(self, other):
         if not isinstance(other, FuncCode):
             return False
-        # fmt: off
-        return ((self.co_argcount, self.co_varnames) <  # NOQA: W504
+        return ((self.co_argcount, self.co_varnames) <
                 (other.co_argcount, other.co_varnames))
-        # fmt: on
 
 
 def _setFuncSignature(self, defaults=None, varnames=(), argcount=-1):

src/Testing/ZopeTestCase/ZopeLite.py

@@ -18,8 +18,9 @@
 
 Typically used as in
 
-import ZopeLite as Zope2 Zope2.installProduct('SomeProduct') app =
-Zope2.app()
+    >>> import ZopeLite as Zope2
+    >>> Zope2.installProduct('SomeProduct')
+    >>> app = Zope2.app()
 """
 
 import os

src/ZPublisher/tests/testHTTPResponse.py

@@ -977,8 +977,7 @@ def test_unauthorized_no_debug_mode(self):
         except Unauthorized as raised:
             self.assertEqual(response.status, 200)  # publisher sets 401 later
             self.assertIn(
-                "You are not authorized "
-                "to access this resource.",
+                "You are not authorized to access this resource.",
                 str(raised)
             )
         else:

src/ZPublisher/tests/test_pubevents.py

@@ -306,7 +306,6 @@ def cleanup():
 
 
 def _succeed():
-    """"""
     return 'success'
 
 

src/webdav/hookable_PUT.py

@@ -8,7 +8,7 @@
 
 
 def PUT_factory(self, name, typ, body):
-    """"""
+    """PUT factory"""
     if TEXT_PATTERN.match(typ):
         return OFS.DTMLMethod.DTMLMethod('', __name__=name)
     return None