Merge pull request #789 from LincolnPuzey/reference_docs_improvements

Small Reference docs improvements

Author: LincolnPuzey

docs/source/reference.rst

@@ -1,3 +1,5 @@
+.. include:: global.rst
+
 API Reference
 =============
 
@@ -53,18 +55,21 @@ Brokers
 .. autoclass:: Broker
    :members:
 .. autoclass:: Consumer
-   :members:  __iter__, __next__, ack, nack, close
+   :members:
 .. autoclass:: MessageProxy
    :members:
 .. autoclass:: dramatiq.brokers.rabbitmq.RabbitmqBroker
    :members:
    :inherited-members:
+   :show-inheritance:
 .. autoclass:: dramatiq.brokers.redis.RedisBroker
    :members:
    :inherited-members:
+   :show-inheritance:
 .. autoclass:: dramatiq.brokers.stub.StubBroker
    :members:
    :inherited-members:
+   :show-inheritance:
 
 
 Middleware
@@ -129,11 +134,16 @@ The class hierarchy for middleware exceptions:
         +-- dramatiq.middleware.TimeLimitExceeded
 
 
-.. autoclass:: dramatiq.middleware.MiddlewareError
-.. autoclass:: dramatiq.middleware.SkipMessage
-.. autoclass:: dramatiq.middleware.Interrupt
-.. autoclass:: dramatiq.middleware.TimeLimitExceeded
-.. autoclass:: dramatiq.middleware.Shutdown
+.. autoexception:: dramatiq.middleware.MiddlewareError
+   :show-inheritance:
+.. autoexception:: dramatiq.middleware.SkipMessage
+   :show-inheritance:
+.. autoexception:: dramatiq.middleware.Interrupt
+   :show-inheritance:
+.. autoexception:: dramatiq.middleware.TimeLimitExceeded
+   :show-inheritance:
+.. autoexception:: dramatiq.middleware.Shutdown
+   :show-inheritance:
 
 
 Results
@@ -149,17 +159,18 @@ Results Middleware
 ^^^^^^^^^^^^^^^^^^
 
 .. autoclass:: dramatiq.results.Results
-   :members:
-   :exclude-members: actor_options, after_process_message, after_skip_message, after_nack
 
 Results Backends
 ^^^^^^^^^^^^^^^^
 
 .. autoclass:: dramatiq.results.ResultBackend
    :members:
 .. autoclass:: dramatiq.results.backends.MemcachedBackend
+   :show-inheritance:
 .. autoclass:: dramatiq.results.backends.RedisBackend
+   :show-inheritance:
 .. autoclass:: dramatiq.results.backends.StubBackend
+   :show-inheritance:
 
 
 Rate Limiters
@@ -177,8 +188,11 @@ Rate limiter backends are used to store metadata about rate limits.
 .. autoclass:: dramatiq.rate_limits.RateLimiterBackend
    :members:
 .. autoclass:: dramatiq.rate_limits.backends.MemcachedBackend
+   :show-inheritance:
 .. autoclass:: dramatiq.rate_limits.backends.RedisBackend
+   :show-inheritance:
 .. autoclass:: dramatiq.rate_limits.backends.StubBackend
+   :show-inheritance:
 
 
 Limiters
@@ -187,8 +201,11 @@ Limiters
 .. autoclass:: dramatiq.rate_limits.RateLimiter
    :members:
 .. autoclass:: dramatiq.rate_limits.BucketRateLimiter
+   :show-inheritance:
 .. autoclass:: dramatiq.rate_limits.ConcurrentRateLimiter
+   :show-inheritance:
 .. autoclass:: dramatiq.rate_limits.WindowRateLimiter
+   :show-inheritance:
 
 Barriers
 ^^^^^^^^
@@ -207,34 +224,48 @@ Workers
 Errors
 ------
 
-.. autoclass:: DramatiqError
+.. autoexception:: DramatiqError
    :members:
-.. autoclass:: BrokerError
+   :show-inheritance:
+.. autoexception:: BrokerError
    :members:
-.. autoclass:: DecodeError
+   :show-inheritance:
+.. autoexception:: DecodeError
    :members:
-.. autoclass:: ActorNotFound
+   :show-inheritance:
+.. autoexception:: ActorNotFound
    :members:
-.. autoclass:: QueueNotFound
+   :show-inheritance:
+.. autoexception:: QueueNotFound
    :members:
-.. autoclass:: ConnectionError
+   :show-inheritance:
+.. autoexception:: ConnectionError
    :members:
-.. autoclass:: ConnectionClosed
+   :show-inheritance:
+.. autoexception:: ConnectionClosed
    :members:
-.. autoclass:: ConnectionFailed
+   :show-inheritance:
+.. autoexception:: ConnectionFailed
    :members:
-.. autoclass:: RateLimitExceeded
+   :show-inheritance:
+.. autoexception:: RateLimitExceeded
    :members:
-.. autoclass:: Retry
+   :show-inheritance:
+.. autoexception:: Retry
    :members:
-.. autoclass:: dramatiq.results.ResultError
+   :show-inheritance:
+.. autoexception:: dramatiq.results.ResultError
    :members:
-.. autoclass:: dramatiq.results.ResultMissing
+   :show-inheritance:
+.. autoexception:: dramatiq.results.ResultMissing
    :members:
-.. autoclass:: dramatiq.results.ResultTimeout
+   :show-inheritance:
+.. autoexception:: dramatiq.results.ResultTimeout
    :members:
-.. autoclass:: dramatiq.results.ResultFailure
+   :show-inheritance:
+.. autoexception:: dramatiq.results.ResultFailure
    :members:
+   :show-inheritance:
 
 Environment Variables
 ---------------------

dramatiq/actor.py

@@ -21,12 +21,12 @@
 from datetime import timedelta
 from inspect import iscoroutinefunction
 from typing import (
-    TYPE_CHECKING,
     Any,
     Awaitable,
     Callable,
     Generic,
     Optional,
+    ParamSpec,
     TypeVar,
     Union,
     overload,
@@ -37,16 +37,11 @@
 from .logging import get_logger
 from .message import Message
 
-if TYPE_CHECKING:
-    from typing_extensions import ParamSpec
-
-    P = ParamSpec("P")
-else:
-    P = TypeVar("P")
-
 #: The regular expression that represents valid queue names.
 _queue_name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9._-]*")
 
+# Type variables for the Actor function's parameters and return type.
+P = ParamSpec("P")
 R = TypeVar("R")
 
 

dramatiq/broker.py

@@ -87,6 +87,7 @@ class Broker:
         to this broker.  If you supply this parameter, you are
         expected to declare *all* middleware.  Most of the time,
         you'll want to use :meth:`.add_middleware` instead.
+        See :ref:`customizing-middleware` for details.
 
     Attributes:
       actor_options(set[str]): The names of all the options actors may

dramatiq/errors.py

@@ -23,7 +23,7 @@
 class DramatiqError(Exception):  # pragma: no cover
     """Base class for all dramatiq errors."""
 
-    def __init__(self, message):
+    def __init__(self, message):  # noqa: B042
         self.message = message
 
     def __str__(self) -> str:
@@ -33,7 +33,7 @@ def __str__(self) -> str:
 class DecodeError(DramatiqError):
     """Raised when a message fails to decode."""
 
-    def __init__(self, message, data, error):
+    def __init__(self, message, data, error):  # noqa: B042
         super().__init__(message)
         self.data = data
         self.error = error
@@ -83,6 +83,6 @@ class Retry(DramatiqError):
     retried after at least that amount of time (in milliseconds).
     """
 
-    def __init__(self, message: str = "", delay: Optional[int] = None):
+    def __init__(self, message: str = "", delay: Optional[int] = None):  # noqa: B042
         super().__init__(message)
         self.delay = delay

dramatiq/rate_limits/backends/memcached.py

@@ -36,8 +36,6 @@ class MemcachedBackend(RateLimiterBackend):
       pool_size(int): The size of the connection pool to use.
       **parameters: Connection parameters are passed directly
         to :class:`pylibmc.Client`.
-
-    .. _memcached: https://memcached.org
     """
 
     def __init__(self, *, pool=None, pool_size=8, **parameters):

dramatiq/rate_limits/bucket.py

@@ -52,8 +52,6 @@ class BucketRateLimiter(RateLimiter):
       key(str): The key to rate limit on.
       limit(int): The maximum number of operations per bucket per key.
       bucket(int): The bucket interval in milliseconds.
-
-    .. |WindowRateLimiter| replace:: :class:`WindowRateLimiter<dramatiq.rate_limits.WindowRateLimiter>`
     """
 
     def __init__(self, backend, key, *, limit=1, bucket=1000):

dramatiq/results/backends/memcached.py

@@ -35,8 +35,6 @@ class MemcachedBackend(ResultBackend):
       pool_size(int): The size of the connection pool to use.
       **parameters: Connection parameters are passed directly
         to :class:`pylibmc.Client`.
-
-    .. _memcached: https://memcached.org
     """
 
     def __init__(self, *, namespace="dramatiq-results", encoder=None, pool=None, pool_size=8, **parameters):

dramatiq/results/errors.py

@@ -35,7 +35,7 @@ class ResultMissing(ResultError):
 class ResultFailure(ResultError):
     """Raised when getting a result from an actor that failed."""
 
-    def __init__(self, message="", orig_exc_type="", orig_exc_msg=""):
+    def __init__(self, message="", orig_exc_type="", orig_exc_msg=""):  # noqa: B042
         super().__init__(message)
 
         self.orig_exc_type = orig_exc_type