rjgtoys.xc: Structured Exceptions for Python

XC encourages a structured, disciplined approach to use of exceptions: where they are raised, it reduces the overhead of declaring exceptions that are specific to a cause, and that contain information of use to the handler. That in turn makes it easier to write concise handlers.

XC exceptions are also easy to use in Web APIs: they serialise into (and deserialise from) language-independent JSON, so they are easy to transport over a network.

• Overview
  • What’s the problem this package solves?
  • What’s a “structured” exception?
  • Structured examples
  • Structured exceptions and APIs
  • What is is built on?
  • Why the name?
• Tutorial
  • Background: Pydantic
  • Exception base classes
  • Declaring an exception
  • Example Exception Declaration
  • Handling an Exception
• Using XC in Web APIs
  • Background
  • The interpretation of RFC7807 in XC
  • API-specific fields
  • Serialisation and Deserialisation
  • FastAPI and Starlette integration
• Documenting XC exceptions
  • Installation
  • Enable the rjgtoys.xc.autodoc extension
  • Example markup and output
• Documenting exception raising behaviour
  • Example: Documentation
• Getting it
• To-do List