README.md

Starception

Beautiful exception page for Starlette and FastAPI apps.

Installation

Install starception using PIP or poetry:

pip install starception
# or
poetry add starception

With syntax highlight support

If you want to colorize code snippets, install pygments library.

pip install starception[pygments]
# or
poetry add starception -E pygments

Screenshot

Dark theme

Features

• secrets masking
• solution hints
• code snippets
• display request info: query, body, headers, cookies
• session contents
• request and app state
• platform information
• environment variables
• syntax highlight
• open paths in editor (vscode only)
• exception chains
• dark theme

Starception automatically masks any value which key contains key, secret, token, password.

Quick start

See example application in examples/ directory of this repository.

Usage

Starception will work only in debug mode so don't forget to set Starlette.debug=True.

To replace built-in debug exception handler call install_error_handler before you create Starlette instance.

from starception import install_error_handler
from starlette.applications import Starlette

install_error_handler()
app = Starlette()

Integration with other frameworks

starception exports starception.exception_handler(request, exc) function, which you can use in your framework. But keep in mind, Starlette will not call any custom exception handler in debug mode (it always uses built-in one).

The snipped below will not work as you expect (unfortunately).

from starlette.applications import Starlette

from starception import exception_handler

app = Starlette(
    debug=True,
    exception_handlers={Exception: exception_handler}
)

Solution hints

If exception class has solution attribute then its content will be used as a solution hint.

class WithHintError(Exception):
    solution = (
        'The connection to the database cannot be established. '
        'Either the database server is down or connection credentials are invalid.'
    )

Opening files in editor

Set your current editor to open paths in your editor/IDE.

from starception import set_editor

set_editor('vscode')

Note, currently only VSCode supported. If you know how to integrate other editors - please PR

Registering link templates

If your editor is not supported, you can add it by calling add_link_template and then selecting it with set_editor.

from starception import set_editor, add_link_template

add_link_template('vscode', 'vscode://file/{path}:{lineno}')
set_editor('vscode')

Credentials

• Look and feel inspired by Phoenix Framework.
• Icons by Tabler Icons.