Make all the docstrings PEP 257 compliant

.github/workflows/ci-cd.yml

@@ -552,7 +552,6 @@ jobs:
         # - linkcheck-docs
         # - metadata-validation
         - pre-commit
-        - pre-commit-pep257
         - setup-check
         # - spellcheck-docs
       fail-fast: false
@@ -574,7 +573,7 @@ jobs:
     - name: Grab the source from Git
       if: >-
         contains(
-        fromJSON('["pre-commit", "pre-commit-pep257", "spellcheck-docs"]'),
+        fromJSON('["pre-commit", "spellcheck-docs"]'),
         matrix.toxenv
         )
       uses: actions/checkout@v3
@@ -583,7 +582,7 @@ jobs:
     - name: Retrieve the project source from an sdist inside the GHA artifact
       if: >-
         !contains(
-        fromJSON('["pre-commit", "pre-commit-pep257", "spellcheck-docs"]'),
+        fromJSON('["pre-commit", "spellcheck-docs"]'),
         matrix.toxenv
         )
       uses: re-actors/checkout-python-sdist@release/v1

.pre-commit-config.yaml

@@ -39,23 +39,6 @@ repos:
   rev: 6.3.0
   hooks:
   - id: pydocstyle
-    exclude: |
-        (?x)
-        tests/dist|
-        cherrypy/(
-            _cp(
-                compat|modpy|logging|error|wsgi|dispatch|tools|reqbody|request
-            )|
-            (
-                lib/(
-                    auth|auth_basic|auth_digest|caching|covercp|
-                    cpstats|cptools|encoding|gctools|httpauth|httputil|
-                    jsontools|lockfile|locking|profiler|reprconf|sessions
-                )|
-                process/(plugins|servers|win32)
-            ).py|
-            test|tutorial
-        )
 
 - repo: https://github.com/Lucas-C/pre-commit-hooks.git
   rev: v1.5.4

cherrypy/_cpcompat.py

@@ -22,17 +22,19 @@
 
 
 def ntob(n, encoding='ISO-8859-1'):
-    """Return the given native string as a byte string in the given
-    encoding.
+    """Convert a native :class:`str` to a :class:`bytes` instance.
+
+    The encoding can be changed to non-ASCII optionally.
     """
     assert_native(n)
     # In Python 3, the native string type is unicode
     return n.encode(encoding)
 
 
 def ntou(n, encoding='ISO-8859-1'):
-    """Return the given native string as a unicode string with the given
-    encoding.
+    """Convert a native :class:`str` to a :class:`str` instance.
+
+    This doesn't actually do anything.
     """
     assert_native(n)
     # In Python 3, the native string type is unicode
@@ -48,6 +50,7 @@ def tonative(n, encoding='ISO-8859-1'):
 
 
 def assert_native(n):
+    """Ensure that input is a native :class:`str`."""
     if not isinstance(n, str):
         raise TypeError('n must be a native str (got %s)' % type(n).__name__)
 

cherrypy/_cpdispatch.py

@@ -25,6 +25,7 @@ class PageHandler(object):
     """Callable which sets response.body."""
 
     def __init__(self, callable, *args, **kwargs):
+        """Initialize the page handler."""
         self.callable = callable
         self.args = args
         self.kwargs = kwargs
@@ -36,6 +37,7 @@ def args(self):
 
     @args.setter
     def args(self, args):
+        """Set the request arguments in order."""
         cherrypy.serving.request.args = args
         return cherrypy.serving.request.args
 
@@ -46,10 +48,12 @@ def kwargs(self):
 
     @kwargs.setter
     def kwargs(self, kwargs):
+        """Set the named request keyword arguments as :class:`dict`."""
         cherrypy.serving.request.kwargs = kwargs
         return cherrypy.serving.request.kwargs
 
     def __call__(self):
+        """Invoke an HTTP handler callable for :class:`PageHandler`."""
         try:
             return self.callable(*self.args, **self.kwargs)
         except TypeError:
@@ -203,15 +207,18 @@ def test_callable_spec(callable, callable_args, callable_kwargs):
     import inspect
 except ImportError:
     def test_callable_spec(callable, args, kwargs):  # noqa: F811
+        """Do nothing as a no-op."""
         return None
 else:
     def getargspec(callable):
+        """Get argument specification using :mod:`inspect`."""
         return inspect.getfullargspec(callable)[:4]
 
 
 class LateParamPageHandler(PageHandler):
+    """Page handler callable with delayed request parameters binding.
 
-    """When passing cherrypy.request.params to the page handler, we do not
+    When passing ``cherrypy.request.params`` to the page handler, we do not
     want to capture that dict too early; we want to give tools like the
     decoding tool a chance to modify the params dict in-between the lookup
     of the handler and the actual calling of the handler. This subclass
@@ -221,14 +228,19 @@ class LateParamPageHandler(PageHandler):
 
     @property
     def kwargs(self):
-        """Page handler kwargs (with cherrypy.request.params copied in)."""
+        """Page handler keyword arguments.
+
+        The returned value contains data merged in
+        from ``cherrypy.request.params``.
+        """
         kwargs = cherrypy.serving.request.params.copy()
         if self._kwargs:
             kwargs.update(self._kwargs)
         return kwargs
 
     @kwargs.setter
     def kwargs(self, kwargs):
+        """Set the named request keyword arguments as :class:`dict`."""
         cherrypy.serving.request.kwargs = kwargs
         self._kwargs = kwargs
 
@@ -238,6 +250,7 @@ def kwargs(self, kwargs):
         string.punctuation, '_' * len(string.punctuation))
 
     def validate_translator(t):
+        """Ensure the translator is of the correct length and size."""
         if not isinstance(t, str) or len(t) != 256:
             raise ValueError(
                 'The translate argument must be a str of len 256.')
@@ -246,6 +259,7 @@ def validate_translator(t):
         string.punctuation, '_' * len(string.punctuation))
 
     def validate_translator(t):
+        """Ensure the translator is of the correct length and size."""
         if not isinstance(t, dict):
             raise ValueError('The translate argument must be a dict.')
 
@@ -273,6 +287,7 @@ class Dispatcher(object):
 
     def __init__(self, dispatch_method_name=None,
                  translate=punctuation_to_underscores):
+        """Initialize the HTTP request dispatcher."""
         validate_translator(translate)
         self.translate = translate
         if dispatch_method_name:
@@ -389,7 +404,9 @@ def find_handler(self, path):
             object_trail.append([name, node, nodeconf, segleft])
 
         def set_conf():
-            """Collapse all object_trail config into cherrypy.request.config.
+            """Collapse all ``object_trail`` conf into config.
+
+            The config being ``cherrypy.request.config``.
             """
             base = cherrypy.config.copy()
             # Note that we merge the config from each node
@@ -505,10 +522,12 @@ def __init__(self, full_result=False, **mapper_options):
         self.mapper.controller_scan = self.controllers.keys
 
     def connect(self, name, route, controller, **kwargs):
+        """Mount an HTTP handler into the router."""
         self.controllers[name] = controller
         self.mapper.connect(name, route, controller=name, **kwargs)
 
     def redirect(self, url):
+        """Perform an HTTP redirect to the given URL."""
         raise cherrypy.HTTPRedirect(url)
 
     def __call__(self, path_info):
@@ -602,6 +621,7 @@ def merge(nodeconf):
 
 
 def XMLRPCDispatcher(next_dispatcher=Dispatcher()):
+    """Chain an HTTP dispatcher variant implementing XML-RPC."""
     from cherrypy.lib import xmlrpcutil
 
     def xmlrpc_dispatch(path_info):

cherrypy/_cperror.py

@@ -137,7 +137,6 @@ class Root:
 
 class CherryPyException(Exception):
     """A base class for CherryPy exceptions."""
-    pass
 
 
 class InternalRedirect(CherryPyException):
@@ -150,6 +149,7 @@ class InternalRedirect(CherryPyException):
     """
 
     def __init__(self, path, query_string=''):
+        """Initialize the internal redirect exception."""
         self.request = cherrypy.serving.request
 
         self.query_string = query_string
@@ -202,6 +202,7 @@ class HTTPRedirect(CherryPyException):
     """The encoding when passed urls are not native strings."""
 
     def __init__(self, urls, status=None, encoding=None):
+        """Initialize the HTTP redirect exception."""
         self.urls = abs_urls = [
             # Note that urljoin will "do the right thing" whether url is:
             #  1. a complete URL with host (e.g. "http://www.example.com/test")
@@ -227,7 +228,9 @@ def __init__(self, urls, status=None, encoding=None):
 
     @classproperty
     def default_status(cls):
-        """The default redirect status for the request.
+        """Redirect status for the request.
+
+        This is the default handler.
 
         RFC 2616 indicates a 301 response code fits our goal; however,
         browser support for 301 is quite messy. Use 302/303 instead. See
@@ -242,8 +245,9 @@ def status(self):
         return status
 
     def set_response(self):
-        """Modify cherrypy.response status, headers, and body to represent
-        self.
+        """Modify ``cherrypy.response`` to represent ``self``.
+
+        Modifies status, headers, and body.
 
         CherryPy uses this internally, but you can also use it to create
         an HTTPRedirect object and set its output without *raising* the
@@ -366,6 +370,7 @@ class HTTPError(CherryPyException):
     """The HTTP Reason-Phrase string."""
 
     def __init__(self, status=500, message=None):
+        """Initialize an HTTP error."""
         self.status = status
         try:
             self.code, self.reason, defaultmsg = _httputil.valid_status(status)
@@ -381,8 +386,9 @@ def __init__(self, status=500, message=None):
         CherryPyException.__init__(self, status, message)
 
     def set_response(self):
-        """Modify cherrypy.response status, headers, and body to represent
-        self.
+        """Modify ``cherrypy.response`` to represent ``self``.
+
+        Modifies status, headers, and body.
 
         CherryPy uses this internally, but you can also use it to create
         an HTTPError object and set its output without *raising* the
@@ -408,6 +414,7 @@ def set_response(self):
         _be_ie_unfriendly(self.code)
 
     def get_error_page(self, *args, **kwargs):
+        """Compose an HTML page with error information."""
         return get_error_page(*args, **kwargs)
 
     def __call__(self):
@@ -432,6 +439,7 @@ class NotFound(HTTPError):
     """
 
     def __init__(self, path=None):
+        """Initialize an HTTP Not Found error."""
         if path is None:
             request = cherrypy.serving.request
             path = request.script_name + request.path_info
@@ -600,7 +608,6 @@ def bare_error(extrabody=None):
     is set in the body. If extrabody is a string, it will be appended
     as-is to the body.
     """
-
     # The whole point of this function is to be a last line-of-defense
     # in handling errors. That is, it must not raise any errors itself;
     # it cannot be allowed to fail. Therefore, don't add to it!

cherrypy/_cplogging.py

@@ -1,4 +1,6 @@
 """
+CherryPy logging module.
+
 Simple config
 =============
 
@@ -126,12 +128,15 @@ class NullHandler(logging.Handler):
     """A no-op logging handler to silence the logging.lastResort handler."""
 
     def handle(self, record):
+        """Handle a log record doing no-op."""
         pass
 
     def emit(self, record):
+        """Emit  a log record doing no-op."""
         pass
 
     def createLock(self):
+        """Lock log write with no-op."""
         self.lock = None
 
 
@@ -167,6 +172,7 @@ class LogManager(object):
     """
 
     def __init__(self, appid=None, logger_root='cherrypy'):
+        """Initialize a CherryPy log manager."""
         self.logger_root = logger_root
         self.appid = appid
         if appid is None:
@@ -217,11 +223,11 @@ def error(self, msg='', context='', severity=logging.INFO,
         )
 
     def __call__(self, *args, **kwargs):
-        """An alias for ``error``."""
+        """Record an error log entry."""
         return self.error(*args, **kwargs)
 
     def access(self):
-        """Write to the access log (in Apache/NCSA Combined Log format).
+        r"""Write to the access log (in Apache/NCSA Combined Log format).
 
         See the
         `apache documentation
@@ -414,7 +420,10 @@ def wsgi(self, newvalue):
 
 
 class WSGIErrorHandler(logging.Handler):
-    "A handler class which writes logging records to environ['wsgi.errors']."
+    """A handler class writing logs to WSGI env.
+
+    Specifically, the target is ``environ['wsgi.errors']``.
+    """
 
     def flush(self):
         """Flushes the stream."""
@@ -450,6 +459,8 @@ def emit(self, record):
 
 
 class LazyRfc3339UtcTime(object):
+    """A postponed timestamp string retrieval class."""
+
     def __str__(self):
         """Return datetime in RFC3339 UTC Format."""
         iso_formatted_now = datetime.datetime.now(