domain-errors 0.1.0__tar.gz → 0.2.0__tar.gz

{domain_errors-0.1.0 → domain_errors-0.2.0}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- **@wrap_errors class-level decoration:** Decorator can now be applied to classes. Fans out over all public callables in `cls.__dict__`, preserving sync/async dispatch per method. Skips private methods, dunder methods, properties, nested classes, and already-decorated methods. Unwraps and rewraps classmethod/staticmethod to preserve semantics. Config (catch, as_, message, capture) applies uniformly to all fanned methods.
+
 ## [0.1.0] - 2026-06-15
 
 ### Added
@@ -14,9 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **DomainError base class:** Typed exception hierarchy with class contract (code, domain, http_status, retryable, default_message).
 - **Instance state:** message (string) and context (dict) for structured logging.
 - **ErrorChain service:** Static methods for wrapping, walking, and analyzing exception chains.
-  - `wrap(err, as_=ErrorType, message=None, **context)` — construct typed domain errors.
-  - `history(err, classifiers=())` — walk exception cascade into ChainLink objects.
-  - `crossings(err, classifiers=())` — identify domain boundary crossings.
+  - `wrap(err, as_=ErrorType, message=None, **context)`: construct typed domain errors.
+  - `history(err, classifiers=())`: walk exception cascade into ChainLink objects.
+  - `crossings(err, classifiers=())`: identify domain boundary crossings.
 - **ChainLink value object:** Structured representation of one exception chain hop, with `to_log_extra()` for JSON-ready logging.
 - **DomainCrossing value object:** Causation hop where errors cross domain boundaries, with `to_log_extra()` for logging.
 - **ChainVia enum:** Tags for how a link entered the chain (ROOT, CAUSE, CONTEXT).

{domain_errors-0.1.0 → domain_errors-0.2.0}/CONTRIBUTING.md

@@ -42,13 +42,13 @@ This project follows these conventions:
 - **Dataclasses**: Use `@dataclass(frozen=True, slots=True)` for immutable value types.
 - **Docstrings**: One-line docstrings for modules, classes, and functions. Use triple quotes even for single lines.
 - **Imports**: Import abstract base classes from `collections.abc` (not `typing`). Use absolute imports (no relative imports).
-- **Methods**: Every method lives in a class or container—no module-level functions. Containers keep methods organized.
+- **Methods**: Every method lives in a class or container: no module-level functions. Containers keep methods organized.
 - **Constants**: Extract magic constants to `constants/` directory only when they are semantically significant (shared across modules or define behavior).
 
 ## Pull Request Flow
 
 1. **Branch**: Create a feature branch off `main` (e.g., `git checkout -b feature/my-feature`).
-2. **Commit**: Make small, clear commits. Each commit author is the person who wrote the code—no co-author or AI attribution trailers.
+2. **Commit**: Make small, clear commits. Each commit author is the person who wrote the code: no co-author or AI attribution trailers.
 3. **Push**: Push your branch and open a pull request on GitHub.
 4. **Review**: The maintainer will review your code, request changes if needed, and merge when ready. Contributors do not merge their own PRs.
 

{domain_errors-0.1.0 → domain_errors-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domain-errors
-Version: 0.1.0
+Version: 0.2.0
 Summary: Typed domain error hierarchy with wrapping and chaining for Python services
 Project-URL: Homepage, https://pypi.org/project/domain-errors/
 Project-URL: Repository, https://github.com/jekhator/domain-errors
@@ -29,11 +29,11 @@ Description-Content-Type: text/markdown
 
 Typed domain error hierarchy with wrapping and chaining for Python services.
 
-Define per-domain exception types with a structured contract (code, domain, HTTP status, retryability). Wrap foreign exceptions into domain errors, walk causation chains, and detect when errors cross domain boundaries—all ready for structured logging.
+Define per-domain exception types with a structured contract (code, domain, HTTP status, retryability). Wrap foreign exceptions into domain errors, walk causation chains, and detect when errors cross domain boundaries: all ready for structured logging.
 
 ## Why?
 
-Service errors should carry semantic meaning: *what* failed (code), *where* it failed (domain), *how* to handle it (HTTP status, retryability), and *why* it happened (context). Cross-service calls risk mixing domains—database errors become API errors become payment errors. `domain-errors` makes this hierarchy explicit and traceable.
+Service errors should carry semantic meaning: *what* failed (code), *where* it failed (domain), *how* to handle it (HTTP status, retryability), and *why* it happened (context). Cross-service calls risk mixing domains: database errors become API errors become payment errors. `domain-errors` makes this hierarchy explicit and traceable.
 
 ```python
 from domain_errors import DomainError, ErrorChain
@@ -165,17 +165,17 @@ error = MyError(
 ```
 
 **Attributes:**
-- `message: str` — the error message
-- `context: dict[str, object]` — structured context data
+- `message: str`: the error message
+- `context: dict[str, object]`: structured context data
 
 ### ErrorChain
 
 Static methods for wrapping, walking, and analyzing exception chains.
 
 **Methods:**
-- `ErrorChain.wrap(err, as_=ErrorType, message=None, **context)` — Construct a typed domain error for the caller to raise `from err`.
-- `ErrorChain.history(err, classifiers=())` — Walk the exception chain; return a tuple of `ChainLink` objects.
-- `ErrorChain.crossings(err, classifiers=())` — Find causation hops where errors crossed domains; return a tuple of `DomainCrossing` objects.
+- `ErrorChain.wrap(err, as_=ErrorType, message=None, **context)`: Construct a typed domain error for the caller to raise `from err`.
+- `ErrorChain.history(err, classifiers=())`: Walk the exception chain; return a tuple of `ChainLink` objects.
+- `ErrorChain.crossings(err, classifiers=())`: Find causation hops where errors crossed domains; return a tuple of `DomainCrossing` objects.
 
 ### ChainLink
 
@@ -245,7 +245,9 @@ links = ErrorChain.history(err, classifiers=(python, http, cloud))
 
 ### @wrap_errors
 
-Decorator for automatic error wrapping. Catches specified exceptions, wraps them into a target DomainError, and captures function arguments for structured logging:
+Decorator for automatic error wrapping. Catches specified exceptions, wraps them into a target DomainError, and captures function arguments for structured logging. Works on both functions and classes (fans out to all public methods, preserving sync/async dispatch).
+
+**Sync and async functions:**
 
 ```python
 from domain_errors import DomainError, wrap_errors
@@ -260,18 +262,6 @@ def read_config(path: str) -> str:
     with open(path) as f:
         return f.read()
 
-# Manual wrapping (before)
-try:
-    config = read_config("/etc/app.yaml")
-except FileNotFoundError as e:
-    raise ErrorChain.wrap(e, as_=StorageError, path=path) from e
-
-# Declarative wrapping (after)
-@wrap_errors(StorageError, catch=(FileNotFoundError, IOError))
-def read_config(path: str) -> str:
-    with open(path) as f:
-        return f.read()
-
 try:
     config = read_config("/etc/app.yaml")
 except StorageError as err:
@@ -280,18 +270,102 @@ except StorageError as err:
     pass
 ```
 
+**Service classes (class-level wrapping):**
+
+```python
+from domain_errors import DomainError, wrap_errors
+
+class PaymentError(DomainError):
+    code = "payment_error"
+    domain = "payment"
+    http_status = 402
+
+@wrap_errors(PaymentError, catch=(ValueError,))
+class PaymentService:
+    def validate_amount(self, amount: int) -> bool:
+        if amount <= 0:
+            raise ValueError("Amount must be positive")
+        return True
+
+    async def process_payment(self, card: str, amount: int) -> str:
+        if not card:
+            raise ValueError("Card required")
+        return f"Processed {amount}"
+
+service = PaymentService()
+
+assert service.validate_amount(100)
+
+try:
+    service.validate_amount(-50)
+except PaymentError as err:
+    print(f"Error: {err.message}")
+    print(f"Context: {err.context}")
+    print(f"Cause: {err.__cause__}")
+```
+
 DomainError instances pass through unchanged; works on sync and async callables; set `capture=False` to omit arguments (e.g., for secrets).
 
+## Service Class Example
+
+A complete service class pattern with error wrapping and context capture:
+
+```python
+from domain_errors import DomainError, ErrorChain
+
+class PaymentService:
+    @staticmethod
+    def process_payment(amount_cents: int) -> dict:
+        try:
+            if amount_cents <= 0:
+                raise ValueError("Amount must be positive")
+            if amount_cents > 999999:
+                raise ValueError("Amount exceeds maximum")
+            return {"status": "success", "amount_cents": amount_cents}
+        except ValueError as e:
+            raise ErrorChain.wrap(
+                e,
+                as_=PaymentError,
+                message=f"Payment validation failed: {e}",
+                amount_cents=amount_cents
+            ) from e
+
+class PaymentError(DomainError):
+    code = "payment_error"
+    domain = "payment"
+    http_status = 400
+    default_message = "Payment processing failed."
+
+# Usage
+try:
+    result = PaymentService.process_payment(5000)
+    print(f"Success: {result}")
+except PaymentError as err:
+    print(f"Error {err.code} in {err.domain}: {err.message}")
+    print(f"Context: {err.context}")
+```
+
+Output:
+
+```
+✓ Successful payment: {'status': 'success', 'amount_cents': 5000}
+✓ Caught PaymentError: code=payment_error, domain=payment
+  Message: Payment validation failed: Amount must be positive
+  Context: {'amount_cents': -100}
+  Chain length: 2
+✓ Caught PaymentError: amount_cents=9999999
+```
+
 ## Documentation
 
-- **DomainError Base:** [docs/apps/domain_error.md](docs/apps/domain_error.md) — class contract, subclassing, message/context semantics
-- **ErrorChain:** [docs/apps/chain.md](docs/apps/chain.md) — wrap, history, crossings, logging integration
-- **@wrap_errors Decorator:** [docs/apps/wrap_errors.md](docs/apps/wrap_errors.md) — declarative error wrapping for functions and async callables
-- **Architecture:** [docs/apps/diagrams.md](docs/apps/diagrams.md) — data flow and domain relationships
+- **DomainError Base:** [docs/apps/domain_error.md](docs/apps/domain_error.md): class contract, subclassing, message/context semantics
+- **ErrorChain:** [docs/apps/chain.md](docs/apps/chain.md): wrap, history, crossings, logging integration
+- **@wrap_errors Decorator:** [docs/apps/wrap_errors.md](docs/apps/wrap_errors.md): declarative error wrapping for functions and async callables
+- **Architecture:** [docs/apps/diagrams.md](docs/apps/diagrams.md): data flow and domain relationships
 
 ## License
 
-Apache 2.0 — see LICENSE file.
+Apache 2.0; see LICENSE file.
 
 ## Contributing
 

{domain_errors-0.1.0 → domain_errors-0.2.0}/README.md

@@ -7,11 +7,11 @@
 
 Typed domain error hierarchy with wrapping and chaining for Python services.
 
-Define per-domain exception types with a structured contract (code, domain, HTTP status, retryability). Wrap foreign exceptions into domain errors, walk causation chains, and detect when errors cross domain boundaries—all ready for structured logging.
+Define per-domain exception types with a structured contract (code, domain, HTTP status, retryability). Wrap foreign exceptions into domain errors, walk causation chains, and detect when errors cross domain boundaries: all ready for structured logging.
 
 ## Why?
 
-Service errors should carry semantic meaning: *what* failed (code), *where* it failed (domain), *how* to handle it (HTTP status, retryability), and *why* it happened (context). Cross-service calls risk mixing domains—database errors become API errors become payment errors. `domain-errors` makes this hierarchy explicit and traceable.
+Service errors should carry semantic meaning: *what* failed (code), *where* it failed (domain), *how* to handle it (HTTP status, retryability), and *why* it happened (context). Cross-service calls risk mixing domains: database errors become API errors become payment errors. `domain-errors` makes this hierarchy explicit and traceable.
 
 ```python
 from domain_errors import DomainError, ErrorChain
@@ -143,17 +143,17 @@ error = MyError(
 ```
 
 **Attributes:**
-- `message: str` — the error message
-- `context: dict[str, object]` — structured context data
+- `message: str`: the error message
+- `context: dict[str, object]`: structured context data
 
 ### ErrorChain
 
 Static methods for wrapping, walking, and analyzing exception chains.
 
 **Methods:**
-- `ErrorChain.wrap(err, as_=ErrorType, message=None, **context)` — Construct a typed domain error for the caller to raise `from err`.
-- `ErrorChain.history(err, classifiers=())` — Walk the exception chain; return a tuple of `ChainLink` objects.
-- `ErrorChain.crossings(err, classifiers=())` — Find causation hops where errors crossed domains; return a tuple of `DomainCrossing` objects.
+- `ErrorChain.wrap(err, as_=ErrorType, message=None, **context)`: Construct a typed domain error for the caller to raise `from err`.
+- `ErrorChain.history(err, classifiers=())`: Walk the exception chain; return a tuple of `ChainLink` objects.
+- `ErrorChain.crossings(err, classifiers=())`: Find causation hops where errors crossed domains; return a tuple of `DomainCrossing` objects.
 
 ### ChainLink
 
@@ -223,7 +223,9 @@ links = ErrorChain.history(err, classifiers=(python, http, cloud))
 
 ### @wrap_errors
 
-Decorator for automatic error wrapping. Catches specified exceptions, wraps them into a target DomainError, and captures function arguments for structured logging:
+Decorator for automatic error wrapping. Catches specified exceptions, wraps them into a target DomainError, and captures function arguments for structured logging. Works on both functions and classes (fans out to all public methods, preserving sync/async dispatch).
+
+**Sync and async functions:**
 
 ```python
 from domain_errors import DomainError, wrap_errors
@@ -238,18 +240,6 @@ def read_config(path: str) -> str:
     with open(path) as f:
         return f.read()
 
-# Manual wrapping (before)
-try:
-    config = read_config("/etc/app.yaml")
-except FileNotFoundError as e:
-    raise ErrorChain.wrap(e, as_=StorageError, path=path) from e
-
-# Declarative wrapping (after)
-@wrap_errors(StorageError, catch=(FileNotFoundError, IOError))
-def read_config(path: str) -> str:
-    with open(path) as f:
-        return f.read()
-
 try:
     config = read_config("/etc/app.yaml")
 except StorageError as err:
@@ -258,18 +248,102 @@ except StorageError as err:
     pass
 ```
 
+**Service classes (class-level wrapping):**
+
+```python
+from domain_errors import DomainError, wrap_errors
+
+class PaymentError(DomainError):
+    code = "payment_error"
+    domain = "payment"
+    http_status = 402
+
+@wrap_errors(PaymentError, catch=(ValueError,))
+class PaymentService:
+    def validate_amount(self, amount: int) -> bool:
+        if amount <= 0:
+            raise ValueError("Amount must be positive")
+        return True
+
+    async def process_payment(self, card: str, amount: int) -> str:
+        if not card:
+            raise ValueError("Card required")
+        return f"Processed {amount}"
+
+service = PaymentService()
+
+assert service.validate_amount(100)
+
+try:
+    service.validate_amount(-50)
+except PaymentError as err:
+    print(f"Error: {err.message}")
+    print(f"Context: {err.context}")
+    print(f"Cause: {err.__cause__}")
+```
+
 DomainError instances pass through unchanged; works on sync and async callables; set `capture=False` to omit arguments (e.g., for secrets).
 
+## Service Class Example
+
+A complete service class pattern with error wrapping and context capture:
+
+```python
+from domain_errors import DomainError, ErrorChain
+
+class PaymentService:
+    @staticmethod
+    def process_payment(amount_cents: int) -> dict:
+        try:
+            if amount_cents <= 0:
+                raise ValueError("Amount must be positive")
+            if amount_cents > 999999:
+                raise ValueError("Amount exceeds maximum")
+            return {"status": "success", "amount_cents": amount_cents}
+        except ValueError as e:
+            raise ErrorChain.wrap(
+                e,
+                as_=PaymentError,
+                message=f"Payment validation failed: {e}",
+                amount_cents=amount_cents
+            ) from e
+
+class PaymentError(DomainError):
+    code = "payment_error"
+    domain = "payment"
+    http_status = 400
+    default_message = "Payment processing failed."
+
+# Usage
+try:
+    result = PaymentService.process_payment(5000)
+    print(f"Success: {result}")
+except PaymentError as err:
+    print(f"Error {err.code} in {err.domain}: {err.message}")
+    print(f"Context: {err.context}")
+```
+
+Output:
+
+```
+✓ Successful payment: {'status': 'success', 'amount_cents': 5000}
+✓ Caught PaymentError: code=payment_error, domain=payment
+  Message: Payment validation failed: Amount must be positive
+  Context: {'amount_cents': -100}
+  Chain length: 2
+✓ Caught PaymentError: amount_cents=9999999
+```
+
 ## Documentation
 
-- **DomainError Base:** [docs/apps/domain_error.md](docs/apps/domain_error.md) — class contract, subclassing, message/context semantics
-- **ErrorChain:** [docs/apps/chain.md](docs/apps/chain.md) — wrap, history, crossings, logging integration
-- **@wrap_errors Decorator:** [docs/apps/wrap_errors.md](docs/apps/wrap_errors.md) — declarative error wrapping for functions and async callables
-- **Architecture:** [docs/apps/diagrams.md](docs/apps/diagrams.md) — data flow and domain relationships
+- **DomainError Base:** [docs/apps/domain_error.md](docs/apps/domain_error.md): class contract, subclassing, message/context semantics
+- **ErrorChain:** [docs/apps/chain.md](docs/apps/chain.md): wrap, history, crossings, logging integration
+- **@wrap_errors Decorator:** [docs/apps/wrap_errors.md](docs/apps/wrap_errors.md): declarative error wrapping for functions and async callables
+- **Architecture:** [docs/apps/diagrams.md](docs/apps/diagrams.md): data flow and domain relationships
 
 ## License
 
-Apache 2.0 — see LICENSE file.
+Apache 2.0; see LICENSE file.
 
 ## Contributing
 

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/chain.md

@@ -33,10 +33,10 @@ def wrap(
 ```
 
 **Parameters:**
-- `err` — the caught exception to wrap
-- `as_` — the target DomainError subclass
-- `message` — optional custom message (defaults to the class `default_message`)
-- `**context` — structured context data (e.g., `user_id=123, attempt=2`)
+- `err`: the caught exception to wrap
+- `as_`: the target DomainError subclass
+- `message`: optional custom message (defaults to the class `default_message`)
+- `**context`: structured context data (e.g., `user_id=123, attempt=2`)
 
 **Example:**
 ```python
@@ -79,8 +79,8 @@ def history(
 ```
 
 **Parameters:**
-- `err` — the root exception (typically the caught exception in an except block)
-- `classifiers` — optional domain classifiers to resolve domains for foreign exceptions
+- `err`: the root exception (typically the caught exception in an except block)
+- `classifiers`: optional domain classifiers to resolve domains for foreign exceptions
 
 **Returns:** A tuple of `ChainLink` objects, root exception first, following `__cause__` (CAUSE via) then `__context__` (CONTEXT via) unless suppressed.
 
@@ -119,8 +119,8 @@ def crossings(
 ```
 
 **Parameters:**
-- `err` — the root exception
-- `classifiers` — optional domain classifiers
+- `err`: the root exception
+- `classifiers`: optional domain classifiers
 
 **Returns:** A tuple of `DomainCrossing` objects, one for each link-to-link transition where domains differ.
 
@@ -172,7 +172,7 @@ class ChainLink:
 ```
 
 **Methods:**
-- `to_log_extra() → dict[str, object]` — Convert to a JSON-ready dict for logger `extra` parameter.
+- `to_log_extra() → dict[str, object]`: Convert to a JSON-ready dict for logger `extra` parameter.
 
 ### `DomainCrossing`
 
@@ -186,7 +186,7 @@ class DomainCrossing:
 ```
 
 **Methods:**
-- `to_log_extra() → dict[str, object]` — Convert to a JSON-ready dict for logger `extra` parameter.
+- `to_log_extra() → dict[str, object]`: Convert to a JSON-ready dict for logger `extra` parameter.
 
 ### `DomainClassifier` (Protocol)
 

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/cloud.md

@@ -60,7 +60,7 @@ def classify(self, err: BaseException) -> str | None:
 
 ### Parameters
 
-- `err` — any caught exception
+- `err`: any caught exception
 
 ### Returns
 
@@ -159,6 +159,6 @@ except Exception as e:
 
 ## See Also
 
-- **ErrorChain:** `docs/apps/chain.md` — how to use classifiers with history/crossings
-- **DomainError Base:** `docs/apps/domain_error.md` — how to define domain-specific errors
-- **Architecture:** `docs/apps/diagrams.md` — system diagram with classifier placement
+- **ErrorChain:** `docs/apps/chain.md`: how to use classifiers with history/crossings
+- **DomainError Base:** `docs/apps/domain_error.md`: how to define domain-specific errors
+- **Architecture:** `docs/apps/diagrams.md`: system diagram with classifier placement

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/diagrams.md

@@ -175,7 +175,7 @@ domains/http/http_client.py  (imports: from __future__ import annotations
 │   BY-ORIGIN: maps any exception DEFINED IN an HTTP-client library  │
 │   to const.HTTP. No import of the libs (string check on            │
 │   type(err).__module__), so NO optional-dep machinery AND complete │
-│   coverage of each lib's whole exception surface — including httpx │
+│   coverage of each lib's whole exception surface: including httpx │
 │   InvalidURL / CookieConflict / StreamError, which sit OUTSIDE the │
 │   httpx.HTTPError tree (a base-class catch would miss them).       │
 │                                                                   │

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/http.md

@@ -60,7 +60,7 @@ def classify(self, err: BaseException) -> str | None:
 
 ### Parameters
 
-- `err` — any caught exception
+- `err`: any caught exception
 
 ### Returns
 
@@ -153,6 +153,6 @@ except Exception as e:
 
 ## See Also
 
-- **ErrorChain:** `docs/apps/chain.md` — how to use classifiers with history/crossings
-- **DomainError Base:** `docs/apps/domain_error.md` — how to define domain-specific errors
-- **Architecture:** `docs/apps/diagrams.md` — system diagram with classifier placement
+- **ErrorChain:** `docs/apps/chain.md`: how to use classifiers with history/crossings
+- **DomainError Base:** `docs/apps/domain_error.md`: how to define domain-specific errors
+- **Architecture:** `docs/apps/diagrams.md`: system diagram with classifier placement

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/python.md

@@ -51,10 +51,10 @@ _FAMILIES: tuple[tuple[tuple[type[BaseException], ...], str], ...] = (
 
 The classifier maps to four coarse domains:
 
-- **`"network"`** — Network-layer exceptions: `ConnectionError`, `TimeoutError`
-- **`"os"`** — Operating system and I/O exceptions: `FileNotFoundError`, `PermissionError`, `OSError` (and subclasses)
-- **`"logic"`** — Logical/programming errors: `ValueError`, `KeyError`, `TypeError`
-- **`"assertion"`** — Assertion failures: `AssertionError`
+- **`"network"`**: Network-layer exceptions: `ConnectionError`, `TimeoutError`
+- **`"os"`**: Operating system and I/O exceptions: `FileNotFoundError`, `PermissionError`, `OSError` (and subclasses)
+- **`"logic"`**: Logical/programming errors: `ValueError`, `KeyError`, `TypeError`
+- **`"assertion"`**: Assertion failures: `AssertionError`
 
 These constants are exported from `domain_errors/domains/constants/python.py`:
 
@@ -71,7 +71,7 @@ def classify(self, err: BaseException) -> str | None:
 
 ### Parameters
 
-- `err` — any caught exception
+- `err`: any caught exception
 
 ### Returns
 
@@ -161,6 +161,6 @@ except Exception as e:
 
 ## See Also
 
-- **ErrorChain:** `docs/apps/chain.md` — how to use classifiers with history/crossings
-- **DomainError Base:** `docs/apps/domain_error.md` — how to define domain-specific errors
-- **Architecture:** `docs/apps/diagrams.md` — system diagram with classifier placement
+- **ErrorChain:** `docs/apps/chain.md`: how to use classifiers with history/crossings
+- **DomainError Base:** `docs/apps/domain_error.md`: how to define domain-specific errors
+- **Architecture:** `docs/apps/diagrams.md`: system diagram with classifier placement

{domain_errors-0.1.0 → domain_errors-0.2.0}/docs/apps/wrap_errors.md

@@ -9,7 +9,7 @@
 
 `wrap_errors` is a function decorator that automatically wraps caught exceptions into a target `DomainError` via `ErrorChain.wrap()`, enabling declarative error handling without boilerplate try-except-raise-from blocks. Use it to convert foreign (non-DomainError) exceptions into domain-specific errors, capture function arguments into error context for structured logging, and let `DomainError` instances pass through unchanged.
 
-It is the suite-wide error-wrapping **standard** for all OSS packages—the decorator analog of manual `ErrorChain.wrap(...) + raise ... from e`.
+It is the suite-wide error-wrapping **standard** for all OSS packages: the decorator analog of manual `ErrorChain.wrap(...) + raise ... from e`.
 
 ## Core Design
 
@@ -26,7 +26,7 @@ The decorator:
 - Catches exceptions matching the `catch` tuple
 - Calls `ErrorChain.wrap(error, as_=..., message=..., **captured_args)` to construct a domain error
 - Raises the domain error with `raise ... from error` (so `__cause__` is the original exception)
-- **Passes `DomainError` (and subclasses) through unchanged**—never re-wraps
+- **Passes `DomainError` (and subclasses) through unchanged**: never re-wraps
 - Captures the call's bound arguments (with defaults applied) into the domain error's `.context`, unless disabled with `capture=False`
 - Works transparently on async functions (awaits the coroutine)
 - Preserves the original function's `__name__`, `__doc__`, and signature via `functools.wraps`
@@ -61,10 +61,10 @@ The returned `WrapErrorsClient` instance is callable; when applied to a function
 
 ## Parameters
 
-- **`as_`** — the target `DomainError` subclass to wrap into (required, positional). Exceptions matching `catch` will be wrapped into this type via `ErrorChain.wrap()`.
-- **`catch`** — tuple of `Exception` types to catch (default `(Exception,)`). Only exceptions in this tuple (or subclasses) are wrapped; others propagate raw. Typed as `tuple[type[Exception], ...]`. Note: `BaseException` (e.g., `KeyboardInterrupt`, `SystemExit`) is intentionally NOT catchable.
-- **`message`** — optional override message passed to the constructed `DomainError` (default `None`). If provided, used instead of `DomainError.default_message`.
-- **`capture`** — when `True` (default), the decorated call's bound arguments are captured into the `DomainError`'s `.context` dict via `inspect.signature(func).bind(...) + apply_defaults()`. Set `False` to omit arguments (e.g., for functions handling secrets).
+- **`as_`**: the target `DomainError` subclass to wrap into (required, positional). Exceptions matching `catch` will be wrapped into this type via `ErrorChain.wrap()`.
+- **`catch`**: tuple of `Exception` types to catch (default `(Exception,)`). Only exceptions in this tuple (or subclasses) are wrapped; others propagate raw. Typed as `tuple[type[Exception], ...]`. Note: `BaseException` (e.g., `KeyboardInterrupt`, `SystemExit`) is intentionally NOT catchable.
+- **`message`**: optional override message passed to the constructed `DomainError` (default `None`). If provided, used instead of `DomainError.default_message`.
+- **`capture`**: when `True` (default), the decorated call's bound arguments are captured into the `DomainError`'s `.context` dict via `inspect.signature(func).bind(...) + apply_defaults()`. Set `False` to omit arguments (e.g., for functions handling secrets).
 
 ## Behavior
 
@@ -96,7 +96,7 @@ def authenticate(username: str, password: str) -> str:
 Guidance:
 - Default to `capture=False` on authentication, payment, and PII-handling functions.
 - Argument capture is all-or-nothing in v0.1.0; field-level redaction (e.g. via a sensitivity-mixin integration) is a planned future enhancement.
-- Captured context is emitted verbatim — redaction is the consumer's logging-pipeline responsibility until field-level support ships.
+- Captured context is emitted verbatim: redaction is the consumer's logging-pipeline responsibility until field-level support ships.
 
 ## Examples
 
@@ -245,6 +245,59 @@ except AuthError as err:
     # Context: {}  (no args captured)
 ```
 
+### Example 6: Class-level decoration (fans out to all public methods)
+
+```python
+from domain_errors import DomainError, wrap_errors
+import asyncio
+
+class PaymentError(DomainError):
+    code = "payment_error"
+    domain = "payment"
+    http_status = 402
+
+@wrap_errors(PaymentError, catch=(ValueError, IOError))
+class PaymentService:
+    def __init__(self, rate_limit: int = 100) -> None:
+        self.rate_limit = rate_limit
+
+    def validate_amount(self, amount: int) -> bool:
+        if amount <= 0:
+            raise ValueError("Amount must be positive")
+        if amount > self.rate_limit:
+            raise ValueError("Amount exceeds rate limit")
+        return True
+
+    async def charge_card(self, card_token: str, amount: int) -> str:
+        if not card_token:
+            raise ValueError("Card token required")
+        return f"Charged {amount} on {card_token}"
+
+service = PaymentService(rate_limit=5000)
+
+assert service.validate_amount(100)
+
+with pytest.raises(PaymentError) as exc_info:
+    service.validate_amount(-50)
+assert exc_info.value.__cause__.__class__ == ValueError
+assert exc_info.value.context == {"amount": -50}
+
+result = asyncio.run(service.charge_card("tok_visa", 1000))
+assert "Charged 1000" in result
+
+with pytest.raises(PaymentError):
+    asyncio.run(service.charge_card("", 1000))
+```
+
+**Class-level behavior:**
+- Decorating a class fans out the decorator over all public callables in `cls.__dict__`.
+- Sync methods get the sync wrapper; async methods get the async wrapper (dispatch preserved per method).
+- Private methods (prefixed with `_`), dunder methods (e.g., `__init__`), properties, and nested classes are skipped.
+- Classmethod and staticmethod are unwrapped, decorated, and rewrapped to preserve their semantics.
+- Methods already decorated with `@wrap_errors` (marked with `__wrap_errors_applied__`) are left untouched (override detection).
+- The `capture`, `message`, and `catch` parameters apply uniformly to all fanned methods.
+- Arguments `self` and `cls` are automatically filtered from the error context to avoid object serialization issues.
+
 ## Usage with ErrorChain
 
 After the decorator wraps an error, walk the chain to classify foreign exceptions and log structured data:
@@ -294,6 +347,6 @@ except ServiceError as err:
 
 ## See Also
 
-- **ErrorChain:** `docs/apps/chain.md` — how to walk chains and use classifiers
-- **DomainError Base:** `docs/apps/domain_error.md` — how to define domain-specific errors
-- **Architecture:** `docs/apps/diagrams.md` — system diagram with decorator placement
+- **ErrorChain:** `docs/apps/chain.md`: how to walk chains and use classifiers
+- **DomainError Base:** `docs/apps/domain_error.md`: how to define domain-specific errors
+- **Architecture:** `docs/apps/diagrams.md`: system diagram with decorator placement