klaida
The problem: It doesn't matter how good your errors and documentation are. Most users just cannot be bothered to read it. Instead of spending 5 minutes reading documentation, they'd rather go in endless circles with an LLM chatbot (which often doesn't have enough context to solve the core issue).
Klaida is a simple exception framework (with a complementary cli tool) where you get:
- a short runtime message: code, summary, optional specifics, and a link
- a docs page per error (HTML + Markdown) with the cause, the fix and any notes
- an index and an
llms.txt - a CI check that the catalog and the generated pages haven't drifted
The idea: users paste the error into a chatbot. The link travels with it, and a chatbot that can browse reads the real fix instead of guessing one.
Use it in a project
# mylib/errors.py
from klaida import DocumentedError
class MylibError(DocumentedError):
docs_base = "https://you.github.io/mylib/errors"
class ShapeMismatch(MylibError):
"""Free-text notes.
This becomes the "Details" section
(Markdown: `code`, ``` blocks, # headings).
"""
code = "E1001"
summary = "Input arrays have different lengths"
cause = "x and y came from different sources, or only one was filtered."
fix = "Check len(x) == len(y) before calling fit()."
hint = "len(x) must equal len(y)" # optional, <= 80 chars
raise ShapeMismatch(f"len(x)={len(x)}, len(y)={len(y)}")
[E1001] Input arrays have different lengths (len(x)=3, len(y)=5)
Hint: len(x) must equal len(y)
See: https://you.github.io/mylib/errors/E1001.html
Build config goes in your project's pyproject.toml (CLI only; docs_base stays
in code because an installed wheel has no pyproject):
[tool.klaida]
modules = ["mylib.errors"] # imported to find error classes
output = "docs/errors" # default
title = "mylib error reference"
llms_txt = "docs/llms.txt" # default: <output>/llms.txt; false to disable
CLI
klaida build # write pages, index, llms.txt
klaida check # CI: duplicate codes, missing cause/fix/docs_base, stale pages
klaida explain E1001 # print one page in the terminal
Want mylib explain E1001 too? from klaida import explain and print
explain(code).
Publishing
example/.github/workflows/docs.yml runs check and deploys docs/ to GitHub
Pages. Pages are static files: E1001.html, E1001.md, index.*, llms.txt.
If you build the rest of your site with MkDocs/Sphinx, point output inside
that site's source folder instead.
Design notes
- Each HTML page has the exact summary in
<title>and<h1>, a<link rel="alternate" type="text/markdown">to the.md, and JSON-LD. - Output is deterministic, so
checkcan diff it against what's on disk. - Codes are case-insensitive for lookup and must be unique across everything imported.
- Generated pages for deleted errors are not removed automatically; delete the file.
Develop
pip install -e ".[dev]" && pytest
cd example && klaida build # see generated output in example/docs/errors
Metadata
Release files for klaida 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| klaida-0.1.0.tar.gz | 14.9 kB | Without provenance | Details for klaida-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| klaida-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for klaida-0.1.0-py3-none-any.whl |
Total release size: 26.6 kB
Release files / klaida-0.1.0.tar.gz
| Download URL | klaida-0.1.0.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91066fdf70e5db2ff141b9dc94c037361a919483edf6b0cb3b778e7e7236a3be
|
|
BLAKE2b-256 checksum How to use checksums |
a1f192060737d67d5d78bd00630a777854ed3b49eb1ff68050a9cb7acf689270
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Release files / klaida-0.1.0-py3-none-any.whl
| Download URL | klaida-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aada41e0b2f1fcbec928a0ba9b88c45435840bb31885b189ae994e071b870262
|
|
BLAKE2b-256 checksum How to use checksums |
a3095ade62f3906b2c6e2a9ae2a4babf25effd0056672b6f914880e6db25372c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.2
|
Security for klaida 0.1.0
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.