simplibs-exception 0.1.0__py3-none-any.whl

simplibs/exception/__init__.py

@@ -0,0 +1,41 @@
+from .exception import SimpleException
+from .utils import bool_or_exception, extract_caller_info
+from .modes import PRETTY, SIMPLE, ONELINE, LOG, ModeBase
+from .settings import SimpleExceptionSettings, SimpleExceptionSettingsError
+
+
+__all__ = [
+    # Core class
+    "SimpleException",
+    # Utils
+    "bool_or_exception",
+    "extract_caller_info",
+    # Modes
+    "PRETTY",
+    "SIMPLE",
+    "ONELINE",
+    "LOG",
+    "ModeBase",
+    # Settings
+    "SimpleExceptionSettings",
+    "SimpleExceptionSettingsError",
+]
+
+
+_DESIGN_NOTES = """
+# simple_exception
+
+## Public API
+| Name                           | Description                                                       |
+|--------------------------------|-------------------------------------------------------------------|
+| `SimpleException`              | Core class — the foundation for all exceptions in the ecosystem   |
+| `bool_or_exception`            | Shortcut for conditional exception raising                        |
+| `extract_caller_info`          | Utility for retrieving call site information from the stack       |
+| `PRETTY`                       | Default mode — structured output with separator lines             |
+| `SIMPLE`                       | Plain text output without decorations                             |
+| `ONELINE`                      | Compact single-line output                                        |
+| `LOG`                          | Key=value format for log parsers                                  |
+| `ModeBase`                     | Base class for custom modes                                       |
+| `SimpleExceptionSettings`      | Central configuration of the library                              |
+| `SimpleExceptionSettingsError` | Exception for errors when changing settings                       |
+"""

simplibs/exception/core/__init__.py

@@ -0,0 +1,20 @@
+from .data import SimpleExceptionData
+from ._internal_exception import SimpleExceptionInternalError
+
+
+_DESIGN_NOTES = """
+# core
+
+## Contents
+The data layer of the library — defines the exception structure and the base
+internal exception that consumes this structure.
+
+| Name                           | Description                                               |
+|--------------------------------|-----------------------------------------------------------|
+| `SimpleExceptionData`          | Data class — exception structure and default values       |
+| `SimpleExceptionInternalError` | Base internal exception — foundation for grouped exceptions|
+
+## Note
+This package has no dependencies on the rest of the library — it is completely
+isolated. Everything else draws from it; nothing points back into it.
+"""

simplibs/exception/core/_internal_exception/SimpleExceptionInternalError.py

@@ -0,0 +1,91 @@
+from dataclasses import dataclass
+# Commons
+from ..data import SimpleExceptionData
+
+
+@dataclass
+class SimpleExceptionInternalError(SimpleExceptionData, Exception):
+    """Internal library exception — no validation, direct output only."""
+
+
+    # Available attributes:
+    error_name: str = "INTERNAL ERROR"
+    # value: object = UNSET
+    # value_label: str = UNSET
+    # expected: str = UNSET
+    # problem: str = UNSET
+    # context: str = UNSET
+    # how_to_fix: tuple[str, ...] = UNSET
+
+
+    # Build the message:
+    def __post_init__(self):
+
+        # 1. Render the message
+        from ...modes import PRETTY
+        rendered_message = PRETTY(self, validate=False)
+
+        # 2. Pass the message to the exception
+        # Instead of super().__init__ we write directly to Exception.args —
+        # this ensures Exception(message) works correctly without overwriting our data.
+        Exception.__init__(self, rendered_message)
+
+
+_DESIGN_NOTES = """
+# SimpleExceptionInternalError
+
+## Purpose
+The base internal exception of the library — completely isolated from
+`SimpleException` logic. Inherits directly from `SimpleExceptionData`
+and `Exception`, with no dependency on the rest of the library beyond
+the `PRETTY` mode.
+
+## Isolation and lazy import
+`PRETTY` is loaded lazily inside `__post_init__` to avoid a circular import —
+`SimpleExceptionInternalError` lives in `core/_internal_exception` and a
+standard top-level import of `modes` would pull it back in. The lazy import
+breaks this cycle and loads the mode only when it is actually needed.
+
+`PRETTY` is called with `validate=False` for two reasons:
+- This is an internal call where the data is already guaranteed to be correct —
+  validation is unnecessary.
+- Validation would re-import `modes` and cause a circular import even through
+  the lazy import.
+
+`PRETTY` is hardcoded — a deliberate choice for reliability. Internal library
+exceptions must produce consistent output regardless of the active settings
+configuration. In the very situations these exceptions handle (misconfiguration,
+logic errors in modes) the settings may be unreliable or only partially
+initialised.
+
+## Group base class
+Serves as the base for grouped internal library exceptions:
+```python
+class SimpleExceptionSettingsError(SimpleExceptionInternalError):
+    error_name: str = "SETTINGS ERROR"
+```
+Grouped exceptions can be caught together:
+```python
+except SimpleExceptionInternalError:
+    ...
+```
+
+## Attributes to define
+A full description of all attributes is in `SimpleExceptionData._DESIGN_NOTES`.
+For internal exceptions, only the following are typically needed:
+
+| Attribute     | Description                                                       |
+|---------------|-------------------------------------------------------------------|
+| `error_name`  | Exception group name — displayed as the heading in the output     |
+| `value`       | The value that caused the exception                               |
+| `value_label` | Label for the value — e.g. the attribute or parameter name        |
+| `expected`    | What was expected                                                 |
+| `problem`     | What is wrong                                                     |
+| `context`     | Additional context — only include if it adds meaningful information|
+| `how_to_fix`  | Tips on how to resolve the error                                  |
+
+## Commented-out attributes
+The commented-out attributes in the class definition serve as a quick
+declarative reference — without reading the documentation it is immediately
+clear which attributes are meaningful to define.
+"""

simplibs/exception/core/_internal_exception/__init__.py

@@ -0,0 +1,16 @@
+from .SimpleExceptionInternalError import SimpleExceptionInternalError
+
+
+_DESIGN_NOTES = """
+# core/_internal_exception
+
+## Contents
+The base internal exception of the library — placed here because it inherits
+directly from `SimpleExceptionData` and is therefore a natural part of the
+data layer. Serves as the foundation for all grouped internal exceptions
+in the library.
+
+| Name                           | Description                                           |
+|--------------------------------|-------------------------------------------------------|
+| `SimpleExceptionInternalError` | Base internal exception — foundation for other groups |
+"""

simplibs/exception/core/data/SimpleExceptionData.py

@@ -0,0 +1,114 @@
+from dataclasses import dataclass
+from simplibs.sentinels import UNSET, UnsetType
+
+
+@dataclass
+class SimpleExceptionData:
+    """Data class defining the structure and default values of SimpleException."""
+
+    # --- Core exception info ---
+    error_name: str = "ERROR"
+    exception: type[Exception] | UnsetType = UNSET
+    _intercepted_exception: str | UnsetType = UNSET
+
+    # --- Info about the inspected value ---
+    value: object = UNSET
+    value_label: str | UnsetType = UNSET
+
+    # --- Exception description ---
+    expected: str | UnsetType = UNSET
+    problem: str | UnsetType = UNSET
+    context: str | UnsetType = UNSET
+    message: str | UnsetType = UNSET
+
+    # --- How to fix ---
+    how_to_fix: tuple[str, ...] | UnsetType = UNSET
+
+    # --- Location info ---
+    _get_location: int | bool = True
+    _skip_locations: tuple[str, ...] = ()
+
+    # --- Single-line output ---
+    _oneline: bool = False
+
+
+_DESIGN_NOTES = """
+# SimpleExceptionData
+
+## Purpose
+A data class defining the structure, default values, and interface of `SimpleException`.
+Completely isolated from the rest of the library — it has no dependencies on
+`SimpleExceptionSettings` or any other library class. This makes it a shared
+foundation for:
+
+1. **`SimpleException`** — subclasses can override public attributes
+   to change default behaviour.
+2. **Internal exceptions** — `SimpleExceptionInternalError` and its subclasses
+   share the same structure without depending on `SimpleException` logic.
+3. **Data protocol for modes** — `ModeBase` expects data with this structure.
+   Custom modes can optionally validate input via `validate=True`.
+
+## Underscore convention
+- **Without underscore** — input parameters that the user can set either as
+  `__init__` arguments or as class-level attributes on subclasses.
+- **With underscore** (`_intercepted_exception`, `_get_location`, etc.) —
+  values that are computed or managed automatically by the system.
+  The user should never set these directly.
+
+## Attribute reference
+
+### Core info
+| Attribute               | Default   | Description                                          |
+|-------------------------|-----------|------------------------------------------------------|
+| `error_name`            | `"ERROR"` | Error name displayed in the exception output         |
+| `exception`             | `UNSET`   | Exception class dynamically added to the MRO         |
+| `_intercepted_exception`| `UNSET`   | Description of a caught exception — set automatically|
+
+### Inspected value
+| Attribute     | Default | Description                                               |
+|---------------|---------|-----------------------------------------------------------|
+| `value`       | `UNSET` | The value that caused the exception                       |
+| `value_label` | `UNSET` | Human-readable label for the value (e.g. `"parameter age"`) |
+
+### Exception description
+| Attribute  | Default | Description                                                      |
+|------------|---------|------------------------------------------------------------------|
+| `expected` | `UNSET` | What was expected (e.g. `"a positive integer"`)                  |
+| `problem`  | `UNSET` | What is wrong (e.g. `"value is negative"`)                       |
+| `context`  | `UNSET` | Broader context — only include if it adds meaningful information  |
+| `message`  | `UNSET` | Free-form message — an alternative to the structured parameters  |
+
+### Location
+| Attribute         | Default | Description                                                         |
+|-------------------|---------|---------------------------------------------------------------------|
+| `_get_location`   | `True`  | Enable/disable location reporting, or set stack depth               |
+| `_skip_locations` | `()`    | Strings matched against file paths — a match causes the frame to be skipped |
+
+### How to fix
+| Attribute    | Default | Description                                                   |
+|--------------|---------|---------------------------------------------------------------|
+| `how_to_fix` | `UNSET` | Tips on how to resolve the error — displayed in the output    |
+
+### Output format
+| Attribute  | Default | Description                                                              |
+|------------|---------|--------------------------------------------------------------------------|
+| `_oneline` | `False` | When `True`, overrides the active mode and prints the exception on a single line. Useful when a specific call site needs compact output regardless of the configured default mode. |
+
+## Overriding defaults on a subclass
+```python
+class MyError(SimpleException):
+    error_name = "MY_ERROR"
+    expected   = "a positive integer"
+    how_to_fix = "Provide a value greater than 0."
+```
+
+## Notes
+- The class itself contains no logic — it is purely declarative.
+  All logic lives in the mixins and in `SimpleException.__init__`.
+- It serves as the data protocol for `ModeBase.render_message` — the data must
+  contain all attributes defined here (they may hold `UNSET`), otherwise
+  validation will fail. Internal calls always pass `validate=False`.
+- Internal exceptions (`SimpleExceptionInternalError` and its subclasses)
+  inherit directly from this class — bypassing `SimpleException` logic
+  and avoiding any circular dependency.
+"""

simplibs/exception/core/data/__init__.py

@@ -0,0 +1,15 @@
+from .SimpleExceptionData import SimpleExceptionData
+
+
+_DESIGN_NOTES = """
+# core/data
+
+## Contents
+The data layer of the library — contains the base structures defining the
+shape of `SimpleException`. These classes contain no logic and serve as a
+pure data contract between the individual parts of the system.
+
+| Name                  | Description                                               |
+|-----------------------|-----------------------------------------------------------|
+| `SimpleExceptionData` | Data class defining the structure and default values      |
+"""

simplibs/exception/exception/SimpleException.py

@@ -0,0 +1,220 @@
+from simplibs.sentinels import UNSET, UnsetType
+# Commons
+from ..core import SimpleExceptionData
+from ..settings import SimpleExceptionSettings as S
+# Inners
+from ._mixins.dunders import DunderInitSubclassMixin, DunderNewMixin
+from ._mixins.serializers import ToDictMixin, ToDebugDictMixin, ToJsonMixin
+from ._mixins.normalizers import (
+    NormalizeParamMixin,
+    ProcessExceptionParamMixin,
+    ProcessHowToFixParamMixin,
+    ProcessSkipLocationsParamMixin,
+    ProcessGetLocationParamMixin
+)
+
+
+class SimpleException(
+    # Base class
+    SimpleExceptionData,            # Base class with class-level attributes
+    # Dunders
+    DunderInitSubclassMixin,        # def __init_subclass__(cls, **kwargs) -> None
+    DunderNewMixin,                 # def __new__(cls, *args, exception: type[Exception] | UnsetType, **kwargs) -> None
+    # Normalizers
+    NormalizeParamMixin,            # def _normalize_param(self, value: Any, attr: str, typ: type) -> Any
+    ProcessExceptionParamMixin,     # def _process_exception_param(self, value: type[Exception]) -> tuple[type[Exception] | UnsetType, str | UnsetType]
+    ProcessHowToFixParamMixin,      # def _process_how_to_fix_param(self, value: tuple[str, ...] | str | UnsetType) -> tuple[str, ...] | UnsetType
+    ProcessSkipLocationsParamMixin, # def _process_skip_locations_param(self, value: tuple[str, ...] | list[str] | str | UnsetType) -> tuple[str, ...]
+    ProcessGetLocationParamMixin,   # def _process_get_location_param(self, value: int | bool | UnsetType) -> int | bool
+    # Serializers
+    ToDictMixin,                    # def to_dict(self) -> dict
+    ToDebugDictMixin,               # def to_debug_dict(self) -> dict
+    ToJsonMixin,                    # def to_json(self) -> str
+    # Base exceptions
+    Exception                       # Base exception enabling the raise mechanism
+):
+    """Structured exception for the Simple ecosystem."""
+
+
+    # -------------------------------------------------------------------------
+    # __init__ — attribute assignment and message assembly
+    # -------------------------------------------------------------------------
+
+    def __init__(
+        self,
+        message: str | UnsetType = UNSET,
+        *,
+        value: object = UNSET,
+        value_label: str | UnsetType = UNSET,
+        expected: str | UnsetType = UNSET,
+        problem: str | UnsetType = UNSET,
+        context: str | UnsetType = UNSET,
+        how_to_fix: tuple[str, ...] | str | UnsetType = UNSET,
+        error_name: str | UnsetType = UNSET,
+        exception: Exception | type[Exception] | UnsetType = UNSET,
+        get_location: bool | int | UnsetType = UNSET,
+        skip_locations: tuple[str, ...] | str | UnsetType = UNSET,
+        oneline: bool = False,
+    ):
+
+        # --- Core info ---
+        self.error_name = self._normalize_param(error_name, "error_name", str)
+        self.exception, self._intercepted_exception = self._process_exception_param(exception)
+
+        # --- Inspected value ---
+        self.value = value
+        self.value_label = self._normalize_param(value_label, "value_label", str)
+
+        # --- Exception description ---
+        self.expected = self._normalize_param(expected, "expected", str)
+        self.problem = self._normalize_param(problem, "problem", str)
+        self.context = self._normalize_param(context, "context", str)
+        self.message = self._normalize_param(message, "message", str)
+
+        # --- How to fix ---
+        self.how_to_fix = self._process_how_to_fix_param(how_to_fix)
+
+        # --- Location ---
+        self._get_location = self._process_get_location_param(get_location)
+        self._skip_locations = self._process_skip_locations_param(skip_locations)
+
+        # --- Single-line output ---
+        self._oneline = self._normalize_param(oneline, "oneline", bool)
+
+        # --- Assemble the message ---
+        self._rendered_message = self._render_message()
+
+        # --- Initialise Exception — bypasses the dataclass __init__ in the MRO ---
+        Exception.__init__(self, self._rendered_message)
+
+
+    # -------------------------------------------------------------------------
+    # Message assembly — delegates to the output mode
+    # -------------------------------------------------------------------------
+
+    def _render_message(self) -> str:
+        """Passes the data to the active mode and returns the assembled string."""
+        if self._oneline:
+            from ..modes import ONELINE
+            return ONELINE(self, validate=False)
+        return S.DEFAULT_MESSAGE_MODE(self, validate=False)
+
+
+    # -------------------------------------------------------------------------
+    # Dunder methods
+    # -------------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(error_name={self.error_name!r}, value={self.value!r})>"
+
+    def __str__(self) -> str:
+        return self._rendered_message
+
+
+_DESIGN_NOTES = """
+# SimpleException
+
+## Purpose
+The core class of the ecosystem — a structured exception that combines a data
+layer, validation, normalisation, and output modes into a single unit. Designed
+so that the exception itself communicates with the developer — describing the
+cause, the circumstances, and the path to a fix.
+
+## Class composition
+`SimpleException` is assembled from mixins, each with a single responsibility:
+
+### Data layer
+- `SimpleExceptionData` — class-level attributes and default values, the source
+  of truth for all parameters. Subclasses can override them.
+
+### Dunders
+- `DunderInitSubclassMixin` — validates subclasses at definition time,
+  catching typos and incorrect types immediately on import.
+- `DunderNewMixin` — dynamically adds `exception` to the instance ancestors,
+  enabling `isinstance(e, ValueError)` without static inheritance.
+
+### Normalizers
+- `NormalizeParamMixin` — normalises simple parameters based on a type check.
+  If the value does not match the expected type, the class-level default is
+  returned. Never raises an exception.
+- `ProcessExceptionParamMixin` — processes the `exception` parameter,
+  accepting both an exception class and an exception instance. Handles the
+  fallback to the class-level default internally when no value is provided —
+  consistent with the other normalisation methods.
+- `ProcessHowToFixParamMixin` — normalises the `how_to_fix` parameter,
+  accepting `str`, `tuple[str, ...]`, or `list[str]` and normalising to
+  `tuple[str, ...]`. Falls back to the class-level default.
+- `ProcessGetLocationParamMixin` — processes the `get_location` parameter,
+  returning the provided value or `S.DEFAULT_GET_LOCATION` from settings.
+  Unlike other normalisations, the fallback comes from settings rather than
+  the class-level default — `get_location` is a global library setting.
+- `ProcessSkipLocationsParamMixin` — processes the `skip_locations` parameter,
+  normalises the input to `tuple[str, ...]` and merges it with
+  `S.DEFAULT_LOCATION_BLACKLIST`. The merge happens inside the method —
+  the user's blacklist and the global blacklist always apply together.
+
+### Serializers
+- `ToDictMixin` — public attributes as a dictionary, UNSET values omitted.
+- `ToDebugDictMixin` — public and private computed attributes as a dictionary.
+- `ToJsonMixin` — public attributes as a JSON string.
+
+## Private vs public attributes
+Attributes are divided by their semantics:
+
+**Public** — exception data, included in `to_dict()`:
+    error_name, exception, value, value_label,
+    expected, problem, context, message, how_to_fix
+
+**Private** — behavioural configuration and computed values, only in `to_debug_dict()`:
+    _get_location, _skip_locations, _oneline,
+    _intercepted_exception, _rendered_message
+
+## Output modes
+The message is assembled in `_render_message()`, which delegates to a mode:
+- `_oneline=True` — uses the `ONELINE` mode (lazy import)
+- otherwise — uses `S.DEFAULT_MESSAGE_MODE` (default: `PRETTY`)
+
+The lazy import of `ONELINE` in `_render_message` is intentional — it prevents
+a circular dependency between the `exception` and `modes` modules.
+
+## Processing flow in `__init__`
+    1. Normalise core info (error_name, exception)
+    2. Normalise the inspected value (value, value_label)
+    3. Normalise the exception description (expected, problem, context, message)
+    4. Process how_to_fix
+    5. Process location (_get_location, _skip_locations)
+    6. Set the output format (_oneline)
+    7. Assemble the message via _render_message()
+    8. Pass the message to Exception.__init__()
+
+## How to create a custom exception
+    class MyValidationError(SimpleException):
+        error_name = "VALIDATION ERROR"
+        expected   = "a positive integer"
+        how_to_fix = (
+            "Provide a value greater than 0.",
+            "Use the int type.",
+        )
+
+    raise MyValidationError(value=age, value_label="parameter age")
+
+Class-level attributes overridden on the subclass take precedence over
+parameters — they can always be overridden again at the call site.
+
+## Using the exception parameter
+    # As a class:
+    raise SimpleException(exception=ValueError, problem="negative value")
+
+    # As an instance from an except block:
+    try:
+        ...
+    except ValueError as e:
+        raise SimpleException(exception=e, problem="negative value")
+
+## Notes
+- `_render_message` stores the result in `self._rendered_message` — a private
+  attribute that `__str__` returns directly. `self.message` remains a clean
+  input parameter accessible via `to_dict()`.
+- All normalisation methods are designed to never raise an exception —
+  in the worst case they return the class-level default or the settings value.
+"""

simplibs/exception/exception/__init__.py

@@ -0,0 +1,27 @@
+from .SimpleException import SimpleException
+
+
+_DESIGN_NOTES = """
+# exception
+
+## Contents
+The core class of the ecosystem — a structured exception combining the data
+layer, validation, normalisation, and output modes.
+
+| Name             | Description                                                      |
+|------------------|------------------------------------------------------------------|
+| `SimpleException`| Core class — the foundation for all exceptions in the Simple ecosystem |
+
+## Usage
+```python
+from simple_exception.exception import SimpleException
+
+raise SimpleException(
+    value_label = "parameter age",
+    expected    = "a positive integer",
+    value       = age,
+    problem     = "value is negative",
+    how_to_fix  = "Provide a value greater than 0.",
+)
+```
+"""

simplibs/exception/exception/_mixins/__init__.py

@@ -0,0 +1,43 @@
+# Dunders
+from .dunders import DunderInitSubclassMixin, DunderNewMixin
+# Normalizers
+from .normalizers import (
+    NormalizeParamMixin,
+    ProcessExceptionParamMixin,
+    ProcessHowToFixParamMixin,
+    ProcessGetLocationParamMixin,
+    ProcessSkipLocationsParamMixin,
+)
+# Serializers
+from .serializers import ToDictMixin, ToDebugDictMixin, ToJsonMixin
+
+
+_DESIGN_NOTES = """
+# exception/_mixins
+
+## Contents
+The aggregation point for all mixins of the `SimpleException` class.
+Imports from subpackages and re-exports them as a unified interface.
+
+| Package       | Mixins                                                                 |
+|---------------|------------------------------------------------------------------------|
+| `dunders`     | DunderInitSubclassMixin, DunderNewMixin                                |
+| `normalizers` | NormalizeParamMixin, ProcessExceptionParamMixin,                       |
+|               | ProcessHowToFixParamMixin, ProcessGetLocationParamMixin,               |
+|               | ProcessSkipLocationsParamMixin                                         |
+| `serializers` | ToDictMixin, ToDebugDictMixin, ToJsonMixin                             |
+
+## Usage
+    from ._mixins import (
+        DunderInitSubclassMixin,
+        DunderNewMixin,
+        NormalizeParamMixin,
+        ProcessExceptionParamMixin,
+        ProcessHowToFixParamMixin,
+        ProcessGetLocationParamMixin,
+        ProcessSkipLocationsParamMixin,
+        ToDictMixin,
+        ToDebugDictMixin,
+        ToJsonMixin,
+    )
+"""

simplibs/exception/exception/_mixins/dunders/InitSubclass.py

@@ -0,0 +1,60 @@
+# Commons
+from ....core import SimpleExceptionData
+# Inners
+from ._utils import check_children_class_attributes
+
+
+class DunderInitSubclassMixin:
+    """Mixin for validating subclasses at definition time."""
+
+    def __init_subclass__(
+        cls,
+        **kwargs
+    ) -> None:
+        """
+        Validates the subclass when it is defined — checks for typos and incorrect attribute types.
+
+        Args:
+            cls: The newly defined class (subclass).
+        """
+        super().__init_subclass__(**kwargs)
+        check_children_class_attributes(SimpleExceptionData, cls)
+
+
+_DESIGN_NOTES = """
+# DunderInitSubclassMixin
+
+## Purpose
+Validates `SimpleException` subclasses at **definition time** — that is, at
+import, not when an instance is created. Developer errors (typos, incorrect
+attribute types) are surfaced immediately.
+
+## Why at class definition time rather than at instantiation
+`__init_subclass__` is called automatically by Python the moment the
+interpreter processes the subclass definition. This means the developer
+receives an error immediately on module import — not somewhere during
+program execution where the root cause would be harder to trace.
+
+## What is checked
+Delegates to `check_children_class_attributes`, which verifies:
+- The subclass contains no attributes not defined in `SimpleExceptionData`
+  (likely typos)
+- Attribute values match the types declared in `SimpleExceptionData`
+
+## Why the logic lives in a separate function
+`__init_subclass__` decides **when** to validate.
+`check_children_class_attributes` decides **how** to validate.
+Separation of concerns — the mixin remains a clean orchestrator that is
+readable at a glance. The validation logic itself (~35 lines with two
+branches and walrus operators) would clutter the method to the point where
+the intent would no longer be obvious without reading the details.
+
+## Notes
+- `super().__init_subclass__(**kwargs)` must always be called first —
+  this ensures correct MRO behaviour under multiple inheritance.
+- The private implementation detail `check_children_class_attributes` lives
+  in the `_utils` subdirectory alongside this mixin — it does not leave
+  that scope.
+- Errors are reported via `SimpleExceptionInternalError` — an internal
+  library exception that signals a developer error, not a runtime error.
+"""