DataExcept 1.5.0__tar.gz → 1.7.0__tar.gz

{dataexcept-1.5.0 → dataexcept-1.7.0}/CHANGELOG.md

@@ -7,18 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-09-17
+
+### Added
+
+- **A product-neutral observability context.** `OperationContext` carries
+  stable system, component and operation labels separately from request, job,
+  correlation, trace and span identifiers. `exception_to_observability_event()`
+  combines that context with the existing redacted exception envelope without
+  coupling DataExcept to a framework or telemetry SDK.
+- **Dependency-free OpenTelemetry support.** Exception conversion exposes the
+  standard `exception.*` attributes plus `dataexcept.failure.*` recovery
+  metadata and can record an exception through the minimal span interface
+  without importing OpenTelemetry.
+- **Dependency-free Sentry enrichment.** Sentry events can carry the redacted
+  DataExcept envelope and operation context while only low-cardinality fields
+  become tags.
+- **W3C Trace Context continuity.** `traceparent` can be parsed without a
+  tracing runtime, with `tracestate` and `baggage` preserved for forwarding.
+  Invalid or all-zero identifiers are rejected rather than replaced with
+  invented provenance, and an incoming parent span ID is never mislabelled as
+  a local span ID.
+- **Framework-neutral execution-boundary adapters** for HTTP requests,
+  background workers and workflow/orchestrator steps. They map stable operation
+  names and correlation identifiers onto the common context while keeping raw
+  request paths, payloads and task arguments out of indexed telemetry. The
+  adapters depend only on plain mappings and therefore fit ASGI/WSGI services,
+  serverless gateways, Celery/RQ/Arq/Dramatiq-style workers, Airflow/Dagster/
+  Prefect/Argo-style orchestrators and custom runtimes without importing them.
+
+### Changed
+
+- Logging helpers can attach `OperationContext` separately from free-form
+  application context, keeping filterable operation identity distinct from
+  arbitrary payload-shaped values.
+- OpenTelemetry and Sentry now project the same operation context so logs,
+  traces and error trackers can correlate one failure consistently.
+- The documentation home page and the README now link every guide the site
+  publishes. Each release had added its guide to the navigation and stopped
+  there, leaving cause-aware exceptions, failure metadata, parsing context,
+  message brokers and the Pino profile reachable only from the sidebar. A test
+  now fails when a page in the navigation is linked from neither landing page,
+  so the two cannot drift apart again.
+
+## [1.6.0] - 2026-09-06
+
+### Added
+
+- **A first-class message-broker hierarchy.** `MessageBrokerError` is a domain
+  root of its own, with `BrokerConnectionError`, `BrokerTimeoutError`,
+  `MessagePublishError`, `MessageConsumeError` and
+  `MessageAcknowledgementError` beneath it. Broker work was reaching for
+  `ServiceConnectionError` and `OperationTimeoutError`, which catch the failure
+  but lose which operation failed and the topic, partition, offset and consumer
+  group it failed at.
+- Structured broker context — `broker`, `topic`, `partition`, `offset`,
+  `consumer_group`, `operation` and `timeout_seconds` — with `broker` redacted
+  when it is a URL, since a bootstrap address routinely carries credentials.
+  The five concrete classes take `cause=` on the canonical contract and set
+  `__cause__`; `MessageBrokerError` itself is a plain base, for catching.
+- **A published Pino profile for the exception envelope.** `exception_to_pino()`
+  and `envelope_to_pino()` project an envelope onto the value Pino logs under
+  its error key, and `pino_profile_schema()`, `PINO_PROFILE_VERSION` and
+  `PINO_PROFILE_ID` expose its versioned JSON Schema. The projection renames
+  `exceptions` to `errors`, matching JavaScript's `AggregateError`, and changes
+  nothing else: identity, attributes, failure metadata, the whole cause,
+  context and member tree, and the redaction already applied to them all come
+  through unchanged.
+- An optional `stack` field, emitted only when a real stack representation
+  exists. `include_stack=True` renders the exception's own traceback, redacted
+  like any other exported string, and omits the field rather than inventing one
+  when the exception was never raised.
+- The Pino projection of every published envelope fixture, beside it under
+  `docs/schema/fixtures/pino/`, so an implementation in another language can
+  check itself against a pair of files rather than against prose.
+- Documented JavaScript and TypeScript usage, including the projection restated
+  in JavaScript and a contract test over the fixture pairs.
+
+Neither addition brings a dependency. The broker hierarchy describes the
+operation rather than the product, so it fits Kafka, RabbitMQ, Pulsar and NATS
+without any broker client; retryability is left unclassified, because a
+rejected publish may be a leader election or a missing topic and the exception
+cannot tell which. The Pino profile adds a JSON document and a function that
+renames one field — no Node.js or Pino, in either direction.
+
+### Changed
+
+- Pull requests now run the release gate's wheel verification: the built wheel
+  is installed, the source tree is deleted, and the suite runs against the
+  installed distribution. A test that quietly depends on the source tree used
+  to surface only at the last job before publication, which is where it
+  surfaced for 1.5.0.
+- The pre-commit hooks are pinned to the versions `poetry.lock` pins, and a
+  test derives one from the other. They had drifted to isort 8 and ruff 0.16.4
+  against a lock on isort 9 and ruff 0.16.5, which is enough to format a commit
+  differently from what CI then checks.
+
 ## [1.5.0] - 2026-09-06
 
 ### Added
 
 - **Redaction-safe source context for parsing failures.** `ParsingError` and
-  `DeserializationError` accept keyword-only `source`, `format`, `preview` and
-  `cause`, so a failure on untrusted content can be described without keeping
-  the content. `source` is redacted when it is a URL and left alone when it is
-  a file path; `preview` is bounded to 200 characters including its truncation
-  marker, decodes bytes as UTF-8
-  with any undecodable byte shown as `\xNN`, and is redacted like any other
-  public attribute.
+  `DeserializationError` take keyword-only `source`, `preview` and `cause`, and
+  `ParsingError` gains a keyword-only `format` that `DeserializationError`
+  already took positionally — so a failure on untrusted content can be
+  described without keeping the content. `source` is redacted when it is a URL
+  and left alone when it is a file path; `preview` is bounded to 200 characters
+  including its truncation marker, decodes bytes as UTF-8 with any undecodable
+  byte shown as `\xNN`, and is redacted like any other public attribute.
 - `cause=` on both classes, following the canonical 1.4.0 contract: recorded as
   `.cause` and set as `__cause__`.
 - **A published JSON Schema for the structured envelope.** The payload
@@ -666,7 +762,9 @@ First public release.
 - Published to PyPI via OIDC trusted publishing; no long-lived API token is
   involved in a release.
 
-[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.2.0...v1.3.0

{dataexcept-1.5.0 → dataexcept-1.7.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it using the following metadata."
 title: "DataExcept"
-version: "1.5.0"
+version: "1.7.0"
 authors:
   - family-names: "Ribeiro"
     given-names: "Diogo"
@@ -11,4 +11,4 @@ authors:
 type: software
 url: "https://github.com/DiogoRibeiro7/DataExcept"
 repository-code: "https://github.com/DiogoRibeiro7/DataExcept"
-date-released: "2026-09-06"
+date-released: "2026-09-17"

{dataexcept-1.5.0 → dataexcept-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DataExcept
-Version: 1.5.0
+Version: 1.7.0
 Summary: A Python package providing structured, easily-extendable custom exception types.
 License-Expression: MIT
 License-File: LICENSE
@@ -44,8 +44,8 @@ Description-Content-Type: text/markdown
 
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
-- **📊 Data Science Focused**: 100 exception classes covering ML pipelines, feature engineering, model training
-- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
+- **📊 Data Science Focused**: 106 exception classes covering ML pipelines, feature engineering, model training
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives, or read it through the [Pino projection](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -186,6 +186,17 @@ DatabaseConnectionError("postgresql://prod-db:5432/analytics")
 QueryExecutionError("SELECT * FROM large_table", original=TimeoutError())
 ```
 
+### 📨 Message Brokers
+
+```python
+from dataexcept.broker_exceptions import *
+
+BrokerConnectionError("kafka://broker.internal:9092", cause=OSError("refused"))
+MessagePublishError("orders", partition=3, cause=OSError("leader not available"))
+MessageConsumeError("orders", partition=3, offset=1042, consumer_group="billing")
+MessageAcknowledgementError("orders", partition=3, offset=1042)
+```
+
 ## 🔍 Advanced Features
 
 ### Smart Logging Integration
@@ -233,7 +244,7 @@ document Python emits.
 ### Command Line Interface
 
 ```bash
-# List every exception class the package exports (100 of them, alphabetically)
+# List every exception class the package exports (106 of them, alphabetically)
 $ dataexcept list
 ApiError
 AuthenticationError
@@ -383,14 +394,21 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Cause-aware Exceptions**: [Wrapping a third-party failure](https://diogoribeiro7.github.io/DataExcept/causes/)
+- **Failure Metadata**: [Transient, permanent, or unclassified](https://diogoribeiro7.github.io/DataExcept/failure_metadata/)
+- **Parsing Context**: [Reporting a failure without keeping the payload](https://diogoribeiro7.github.io/DataExcept/parsing_context/)
+- **Message Brokers**: [Publish, consume and acknowledgement failures](https://diogoribeiro7.github.io/DataExcept/brokers/)
 - **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
+- **Pino Interoperability**: [Consuming envelopes from Node.js](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🎓 Citation
 
 If you use DataExcept in your research, please cite the exact release you used.
-The canonical release metadata is maintained in [CITATION.cff](CITATION.cff).
+The canonical release metadata is maintained in [CITATION.cff](CITATION.cff), and
+the [citation guide](https://diogoribeiro7.github.io/DataExcept/citation/)
+explains how to get the APA and BibTeX forms from it.
 
 ## 📄 License
 

{dataexcept-1.5.0 → dataexcept-1.7.0}/README.md

@@ -17,8 +17,8 @@
 
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
-- **📊 Data Science Focused**: 100 exception classes covering ML pipelines, feature engineering, model training
-- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
+- **📊 Data Science Focused**: 106 exception classes covering ML pipelines, feature engineering, model training
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives, or read it through the [Pino projection](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -159,6 +159,17 @@ DatabaseConnectionError("postgresql://prod-db:5432/analytics")
 QueryExecutionError("SELECT * FROM large_table", original=TimeoutError())
 ```
 
+### 📨 Message Brokers
+
+```python
+from dataexcept.broker_exceptions import *
+
+BrokerConnectionError("kafka://broker.internal:9092", cause=OSError("refused"))
+MessagePublishError("orders", partition=3, cause=OSError("leader not available"))
+MessageConsumeError("orders", partition=3, offset=1042, consumer_group="billing")
+MessageAcknowledgementError("orders", partition=3, offset=1042)
+```
+
 ## 🔍 Advanced Features
 
 ### Smart Logging Integration
@@ -206,7 +217,7 @@ document Python emits.
 ### Command Line Interface
 
 ```bash
-# List every exception class the package exports (100 of them, alphabetically)
+# List every exception class the package exports (106 of them, alphabetically)
 $ dataexcept list
 ApiError
 AuthenticationError
@@ -356,14 +367,21 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Cause-aware Exceptions**: [Wrapping a third-party failure](https://diogoribeiro7.github.io/DataExcept/causes/)
+- **Failure Metadata**: [Transient, permanent, or unclassified](https://diogoribeiro7.github.io/DataExcept/failure_metadata/)
+- **Parsing Context**: [Reporting a failure without keeping the payload](https://diogoribeiro7.github.io/DataExcept/parsing_context/)
+- **Message Brokers**: [Publish, consume and acknowledgement failures](https://diogoribeiro7.github.io/DataExcept/brokers/)
 - **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
+- **Pino Interoperability**: [Consuming envelopes from Node.js](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🎓 Citation
 
 If you use DataExcept in your research, please cite the exact release you used.
-The canonical release metadata is maintained in [CITATION.cff](CITATION.cff).
+The canonical release metadata is maintained in [CITATION.cff](CITATION.cff), and
+the [citation guide](https://diogoribeiro7.github.io/DataExcept/citation/)
+explains how to get the APA and BibTeX forms from it.
 
 ## 📄 License
 

{dataexcept-1.5.0 → dataexcept-1.7.0}/dataexcept/__init__.py

@@ -25,6 +25,7 @@ except ModuleNotFoundError:  # pragma: no cover - fallback for Python <3.11
 from importlib import metadata
 
 from . import (  # noqa: F401
+    broker_exceptions,
     database_exceptions,
     dataengineering_exceptions,
     datascience_exceptions,
@@ -37,6 +38,14 @@ from . import (  # noqa: F401
     security_exceptions,
 )
 from .base import DataExceptError, UnpicklableCause, UnpicklableValue
+from .broker_exceptions import (
+    BrokerConnectionError,
+    BrokerTimeoutError,
+    MessageAcknowledgementError,
+    MessageBrokerError,
+    MessageConsumeError,
+    MessagePublishError,
+)
 from .database_exceptions import (
     DatabaseConnectionError,
     DatabaseError,
@@ -112,24 +121,15 @@ from .exceptions import (
     WebhookError,
 )
 from .failure_metadata import FailureKind, FailureMetadata
-from .io_exceptions import (
-    CustomIOError,
-    FileLockError,
-    FileReadError,
-    FileWriteError,
-)
-from .logging_helpers import (
-    Context,
-    log_and_raise,
-    log_exception,
-    log_then_raise,
-)
+from .io_exceptions import CustomIOError, FileLockError, FileReadError, FileWriteError
+from .logging_helpers import Context, log_and_raise, log_exception, log_then_raise
 from .network_exceptions import (
     ConnectionTimeoutError,
     HostUnreachableError,
     NetworkError,
     ProtocolError,
 )
+from .observability import OperationContext, exception_to_observability_event
 from .pandas_exceptions import (
     DtypeMismatchError,
     IndexAlignmentError,
@@ -138,6 +138,7 @@ from .pandas_exceptions import (
     PandasError,
     PandasIOError,
 )
+from .pino import envelope_to_pino, exception_to_pino
 from .pipeline_exceptions import (
     ApiError,
     DataFetchError,
@@ -157,7 +158,10 @@ from .pipeline_exceptions import (
 from .schema import (
     ENVELOPE_SCHEMA_ID,
     ENVELOPE_SCHEMA_VERSION,
+    PINO_PROFILE_ID,
+    PINO_PROFILE_VERSION,
     envelope_schema,
+    pino_profile_schema,
 )
 from .security_exceptions import (
     DecryptionError,
@@ -165,6 +169,7 @@ from .security_exceptions import (
     InvalidTokenError,
     SecurityError,
 )
+from .sentry import enrich_sentry_event
 from .serialization import exception_to_dict, exception_to_json
 from .wrapping import wrap, wrapping
 
@@ -179,6 +184,8 @@ __all__ = [
     "AuthorizationError",
     "BatchProcessingError",
     "BiasDetectionError",
+    "BrokerConnectionError",
+    "BrokerTimeoutError",
     "ConfigurationError",
     "ConnectionTimeoutError",
     "ConvergenceError",
@@ -230,6 +237,10 @@ __all__ = [
     "JobCancellationError",
     "JobError",
     "MergeKeyError",
+    "MessageAcknowledgementError",
+    "MessageBrokerError",
+    "MessageConsumeError",
+    "MessagePublishError",
     "MissingColumnError",
     "MissingDataError",
     "MissingPartitionError",
@@ -276,13 +287,22 @@ __all__ = [
     "wrapping",
     "exception_to_dict",
     "exception_to_json",
+    "exception_to_observability_event",
+    "OperationContext",
     "ENVELOPE_SCHEMA_ID",
     "ENVELOPE_SCHEMA_VERSION",
     "envelope_schema",
+    "PINO_PROFILE_ID",
+    "PINO_PROFILE_VERSION",
+    "pino_profile_schema",
+    "envelope_to_pino",
+    "exception_to_pino",
+    "enrich_sentry_event",
     "Context",
     "log_and_raise",
     "log_exception",
     "log_then_raise",
+    "broker_exceptions",
     "database_exceptions",
     "dataengineering_exceptions",
     "datascience_exceptions",

dataexcept-1.7.0/dataexcept/broker_exceptions.py

@@ -0,0 +1,247 @@
+"""Custom exceptions for message-broker operations.
+
+A broker is a data-engineering boundary like a database or an object store, and
+it fails in ways that are specific to it: a publish is rejected, a consumer
+cannot reach its group, an offset is never committed. Mapping those onto
+``ServiceConnectionError`` and ``OperationTimeoutError`` loses which of them
+happened, and with it the topic, partition, offset and consumer group that say
+where.
+
+The hierarchy is deliberately about the *operation* rather than the product.
+Kafka, RabbitMQ, Pulsar and NATS disagree about almost everything else, but all
+four connect, publish, consume and acknowledge, so a pipeline can catch these
+without knowing which broker or client library is underneath -- and DataExcept
+depends on none of them.
+
+Failure metadata stays at the conservative default. A broker refusing a publish
+may be a leader election that resolves in a second or a topic that does not
+exist, and the exception cannot tell which. An integration that *does* know --
+because it read the broker's own error code -- attaches that with
+``with_failure_metadata`` or ``wrap(..., failure_metadata=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._causes import resolve_cause
+from .base import DataExceptError
+from .redaction import redact_if_url
+
+
+def _describe_position(
+    topic: str,
+    partition: Optional[int] = None,
+    offset: Optional[int] = None,
+    consumer_group: Optional[str] = None,
+) -> str:
+    """Render as much of a message's coordinates as the caller supplied."""
+    parts = [f"topic '{topic}'"]
+    if partition is not None:
+        parts.append(f"partition {partition}")
+    if offset is not None:
+        parts.append(f"offset {offset}")
+    if consumer_group is not None:
+        parts.append(f"group '{consumer_group}'")
+    return ", ".join(parts)
+
+
+def _on_broker(broker: Optional[str]) -> str:
+    return f" on broker '{broker}'" if broker else ""
+
+
+class MessageBrokerError(DataExceptError):
+    """Base exception for message-broker failures.
+
+    Catching this catches every broker failure the library raises, without
+    catching a database or HTTP one.
+    """
+
+    pass
+
+
+class BrokerConnectionError(MessageBrokerError):
+    """Raised when a connection to the broker cannot be established."""
+
+    def __init__(
+        self,
+        broker: str,
+        message: Optional[str] = None,
+        *,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        """Initialize BrokerConnectionError.
+
+        Args:
+            broker: The broker being connected to. A bootstrap address, a
+                cluster name, or a URL -- redacted when it is a URL, since one
+                routinely carries credentials.
+            message: Optional custom error message.
+            cause: Optional underlying exception, also set as ``__cause__``.
+        """
+        self.broker = redact_if_url(broker)
+        self.cause = resolve_cause(cause=cause)
+        default = f"Failed to connect to message broker '{self.broker}'"
+        if self.cause:
+            default += f": {self.cause}"
+        super().__init__(message or default)
+
+
+class BrokerTimeoutError(MessageBrokerError):
+    """Raised when a broker operation exceeds its time limit."""
+
+    def __init__(
+        self,
+        broker: str,
+        operation: Optional[str] = None,
+        timeout_seconds: Optional[float] = None,
+        message: Optional[str] = None,
+        *,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        """Initialize BrokerTimeoutError.
+
+        Args:
+            broker: The broker the operation was waiting on.
+            operation: What was being attempted, such as ``"publish"``.
+            timeout_seconds: The limit that was exceeded.
+            message: Optional custom error message.
+            cause: Optional underlying exception, also set as ``__cause__``.
+        """
+        self.broker = redact_if_url(broker)
+        self.operation = operation
+        self.timeout_seconds = timeout_seconds
+        self.cause = resolve_cause(cause=cause)
+        attempted = (
+            f"Broker operation '{operation}'" if operation else "Broker operation"
+        )
+        default = f"{attempted} timed out"
+        if timeout_seconds is not None:
+            default += f" after {timeout_seconds}s"
+        default += _on_broker(self.broker)
+        if self.cause:
+            default += f": {self.cause}"
+        super().__init__(message or default)
+
+
+class MessagePublishError(MessageBrokerError):
+    """Raised when publishing a message fails."""
+
+    def __init__(
+        self,
+        topic: str,
+        broker: Optional[str] = None,
+        partition: Optional[int] = None,
+        message: Optional[str] = None,
+        *,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        """Initialize MessagePublishError.
+
+        Args:
+            topic: The topic, queue or subject published to.
+            broker: Optional broker the publish was addressed to.
+            partition: Optional partition the message was keyed to.
+            message: Optional custom error message.
+            cause: Optional underlying exception, also set as ``__cause__``.
+        """
+        self.topic = topic
+        self.broker = redact_if_url(broker)
+        self.partition = partition
+        self.cause = resolve_cause(cause=cause)
+        position = _describe_position(topic, partition)
+        default = f"Failed to publish to {position}{_on_broker(self.broker)}"
+        if self.cause:
+            default += f": {self.cause}"
+        super().__init__(message or default)
+
+
+class MessageConsumeError(MessageBrokerError):
+    """Raised when consuming a message fails."""
+
+    def __init__(
+        self,
+        topic: str,
+        broker: Optional[str] = None,
+        partition: Optional[int] = None,
+        offset: Optional[int] = None,
+        consumer_group: Optional[str] = None,
+        message: Optional[str] = None,
+        *,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        """Initialize MessageConsumeError.
+
+        Args:
+            topic: The topic, queue or subject consumed from.
+            broker: Optional broker the consumer was reading from.
+            partition: Optional partition being read.
+            offset: Optional offset the failure happened at.
+            consumer_group: Optional consumer group the reader belongs to.
+            message: Optional custom error message.
+            cause: Optional underlying exception, also set as ``__cause__``.
+        """
+        self.topic = topic
+        self.broker = redact_if_url(broker)
+        self.partition = partition
+        self.offset = offset
+        self.consumer_group = consumer_group
+        self.cause = resolve_cause(cause=cause)
+        position = _describe_position(topic, partition, offset, consumer_group)
+        default = f"Failed to consume from {position}{_on_broker(self.broker)}"
+        if self.cause:
+            default += f": {self.cause}"
+        super().__init__(message or default)
+
+
+class MessageAcknowledgementError(MessageBrokerError):
+    """Raised when acknowledging or committing a message fails.
+
+    Distinct from a consume failure on purpose: the message was read and
+    processed, and it is the record of that which did not stick -- so it will
+    be delivered again.
+    """
+
+    def __init__(
+        self,
+        topic: str,
+        broker: Optional[str] = None,
+        partition: Optional[int] = None,
+        offset: Optional[int] = None,
+        consumer_group: Optional[str] = None,
+        message: Optional[str] = None,
+        *,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        """Initialize MessageAcknowledgementError.
+
+        Args:
+            topic: The topic, queue or subject the message came from.
+            broker: Optional broker the acknowledgement was sent to.
+            partition: Optional partition the message was read from.
+            offset: Optional offset that failed to commit.
+            consumer_group: Optional consumer group committing the offset.
+            message: Optional custom error message.
+            cause: Optional underlying exception, also set as ``__cause__``.
+        """
+        self.topic = topic
+        self.broker = redact_if_url(broker)
+        self.partition = partition
+        self.offset = offset
+        self.consumer_group = consumer_group
+        self.cause = resolve_cause(cause=cause)
+        position = _describe_position(topic, partition, offset, consumer_group)
+        default = f"Failed to acknowledge {position}{_on_broker(self.broker)}"
+        if self.cause:
+            default += f": {self.cause}"
+        super().__init__(message or default)
+
+
+__all__ = [
+    "MessageBrokerError",
+    "BrokerConnectionError",
+    "BrokerTimeoutError",
+    "MessagePublishError",
+    "MessageConsumeError",
+    "MessageAcknowledgementError",
+]