Skip to main content

🎯simplibs-exception

PyPI Python Licence

An exception that tries to be a friend.

A structured Python exception framework that doesn't just crash—it explains what went wrong, why it happened, and how to fix it. Beautiful terminal layouts, programmatic analytics exporters, zero filler.

═════════════════════════════════════════════════════════════════
⚠️ VALIDATION ERROR: parameter age
═════════════════════════════════════════════════════════════════
Expected:  a positive integer
Got:       -5 (int)
Problem:   value is negative
File info: File: main.py | Line: 42 | Function: validate
File path: /path/to/project/main.py
─────────────────────────────────────────────────────────────────
🔧 How to fix:
     • Provide a value greater than 0.
     • Use the int type.
═════════════════════════════════════════════════════════════════

🧭 The Core Philosophy

Standard Python exceptions tell you where code broke, but they leave you guessing about what was inside your variables or how to recover. You end up stuffing complex debugging telemetry into ad-hoc f-strings.

simplibs-exception changes the paradigm. Instead of chaotic crashes, you get diagnostic reports: highly structured, easily readable context containing your expected vs. obtained values, specific problem statements, and actionable remediation steps.


📦 Installation

pip install simplibs-exception

⚠️ Migration Note (v0.2.x → v1.0.0+):
Please note that version 1.0.0 and above introduces a breaking change and is not backward compatible with previous releases. The parameter value_label in SimpleExceptionData (and SimpleException) has been renamed to label for greater semantic precision and broader context applicability. If you are upgrading from an older version, please update your codebase accordingly.


🚀 Quick Start in 60 Seconds

You can initialize SimpleException as an empty marker and enrich it incrementally. All parameters are optional.

Level 1: The Marker

Just mark a failure point—the framework automatically captures file, line, and function context.

from simplibs.exception import SimpleException

raise SimpleException()
# ⚠️ ERROR: File: main.py | Line: 12 | Function: process

Level 2: Custom Text Message

Use it like a traditional exception but wrapped in cleaner console formatting.

raise SimpleException("Database connection timed out after 30s")

Level 3: The Full Diagnostic

Provide full structured data to turn a simple crash into an elite debugging card.

raise SimpleException(
    label      = "parameter age",
    expected   = "a positive integer",
    value      = age,
    problem    = "value is negative",
    how_to_fix = "Provide a value greater than 0."
)

🛠️ The Architecture: 3 Pillars

To keep the library clean and highly optimized, the logic is separated into three decoupled components:

┌────────────────────────────────┐
│   SimpleExceptionSettings      │ ◄── Global configuration, overrides, and safety locks
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│      SimpleExceptionData       │ ◄── Immutable data storage, serializers (.to_dict())
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│        SimpleException         │ ◄── Active runtime manager, dynamic MRO, and execution
└────────────────────────────────┘

1. SimpleExceptionData (The Model)

Acts as the passive data schema. It owns the raw parameters, lazy caching properties, and public analytics state exporters (to_dict(), to_json()).

➡️ README_DATA.md

2. SimpleException (The Runtime Engine)

The active execution manager. It overrides dataclass-level __init__ routines, manages dynamic Method Resolution Order (MRO) injection, triggers subclass compile-time audits, and orchestrates terminal rendering.

➡️ README_EXCEPTION.md

3. SimpleExceptionSettings (The Control Center)

A validated global configuration interface governed by a strict metaclass. It lets you customize default behaviors, set value truncation boundaries, and control stack trace filtering securely.

➡️ README_SETTINGS.md


🎨 Output Modes

Your exception can speak different visual formats depending on your deployment environment:

  • PRETTY (Default): Beautifully framed visual card layout optimized for console output during development.
  • SIMPLE: Plain-text structured layout without Unicode borders. Perfect for standard files and log processors.
  • ONELINE: Everything compressed into a single line. Perfect for standard application log streaming.
  • LOG: Highly optimized, machine-readable key=value format designed for log forwarders (Datadog, Splunk, ELK).

➡️ README_MODES.md

You can easily build your own layout formats (e.g., HTML, Slack message blocks) by subclassing the base template manager ModeBase.

➡️ README_CUSTOM_MODES.md


📚 Shared Exception Library

Beyond the base SimpleException, the framework ships a categorized tree of ready-to-use, general-purpose exceptions — SimpleError as the common root, plus families like ValidationError/ParamError, StateError/InitializationError/ConfigurationError, ResourceError/NotFoundError/AlreadyExistsError/AccessError, OperationError, ConversionError, and DependencyError. Every simplibs library imports what it needs from here instead of redefining an equivalent exception locally.

from simplibs.exception.exceptions import ParamError

raise ParamError(label="age", expected="a non-negative integer", value=-5)

➡️ README_EXCEPTIONS.md


🧰 Built-in Developer Tools

The framework provides helper functions to minimize repetitive error-handling boilerplate:

bool_or_exception

A bi-modal validation shortcut. It either gracefully returns False or raises a fully-structured exception based on a flag, eliminating verbose conditional block code.

from simplibs.exception.tools import bool_or_exception

def validate_age(age: int, return_bool: bool = False) -> bool:
    if age < 0:
        return bool_or_exception(return_bool, value=age, label="age", expected="positive integer")
    return True

➡️ README_BOOL_OR_EXCEPTION.md

build_validation_error

A factory that builds a fully structured ValidationError for a failed user-supplied callable rule (a lambda or plain function), automatically extracting the callable's name into the diagnostic message.

from simplibs.exception.exceptions.validations_errors.builders import build_validation_error

if not rule(value):
    raise build_validation_error(rule, value, value_name="age")

➡️ README_BUILD_VALIDATION_ERROR.md

raise_with_location_offset

A single-line utility that takes any exception, dynamically shifts its stack trace tracking depth backwards, and raises it.

raise_with_location_offset(SimpleException("Failed"), offset=1)

➡️ README_RAISE_WITN_LOCATION_OFFSET.md

@raise_location_offset (Decorator)

An Aspect-Oriented decorator that intercepts bubbling exceptions and re-targets their trace location to the caller's call-site. Excellent for writing transparent gatekeeper and validator helpers.

@raise_location_offset(offset=1)
def assert_positive(n: int):
    if n <= 0:
        raise SimpleException(value=n, expected="strictly positive")

➡️ README_RAISE_LOCATION_OFFSET.md


🧪 Advanced Testing Ecosystem

Writing unit tests for custom exceptions, validation functions, and error parameters often leads to repetitive boilerplate. To solve this, simplibs-exception includes a complete, self-contained testing framework under its testing namespace.

With our testing tools, you can run bulk matrix-driven evaluations, validate class MRO integrity, and audit error payloads with minimal code:

from simplibs.exception.testing import assert_exception_class

# Automatically audits inheritance, defaults, constructors, and serialization protocols
assert_exception_class(MyCustomError)

➡️ README_TESTING.md


☯️ About simplibs

All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:

  • Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
  • Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
  • Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
  • Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
  • Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.

🤝 Contributing & Community

This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!

  • Want to contribute? Feel free to open an Issue or submit a Pull Request.
  • Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.

📝 License

This library is released under the MIT License. Build great things!


▲ Back to Top

Metadata

Release files for simplibs-exception 1.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simplibs-exception 1.1.4
File Size Uploaded Provenance Actions
simplibs_exception-1.1.4.tar.gz 116.4 kB Without provenance Details for simplibs_exception-1.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simplibs-exception 1.1.4
File Interpreter ABI Platform Actions
simplibs_exception-1.1.4-py3-none-any.whl Python 3 none any Details for simplibs_exception-1.1.4-py3-none-any.whl

Total release size: 298.0 kB

Release files / simplibs_exception-1.1.4.tar.gz

Download URL simplibs_exception-1.1.4.tar.gz
Size 116.4 kB
Tags Source
SHA-256 checksum
How to use checksums
800c2c7b7d467acdba296e8dd52268f3fce5ef469551206b23df88ff8f80edef
BLAKE2b-256 checksum
How to use checksums
28c177f74b97603ea1593a827c85582c1e40d9bf78308088a5f6375397ab1642
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / simplibs_exception-1.1.4-py3-none-any.whl

Download URL simplibs_exception-1.1.4-py3-none-any.whl
Size 181.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5b946094476f98329bea61b318fa828e24b98f7bd8d985a33f29770080e9dfea
BLAKE2b-256 checksum
How to use checksums
73c03486bc9b6a21005db7d38f86c67b6a018853a0bb60878e791f72a4b18777
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for simplibs-exception 1.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page