starception 0.5.1

Beautiful debugging page for Starlette apps.

Starception

Beautiful exception page for Starlette and FastAPI apps.

Installation

Install starception using PIP or poetry:

pip install starception
# or
poetry add starception

Screenshot

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

The middleware will automatically mask 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 debug=True for local development.

Monkey patching Starlette

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

Currently, this is a recommended approach.

from starception import install_error_handler
from starlette.applications import Starlette

install_error_handler()
app = Starlette()

Using middleware

To render a beautiful exception page you need to install a StarceptionMiddleware middleware to your application.

Note, to catch as many exceptions as possible the middleware has to be the first one in the stack.

import typing

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.requests import Request
from starlette.routing import Route

from starception import StarceptionMiddleware


async def index_view(request: Request) -> typing.NoReturn:
    raise TypeError('Oops, something really went wrong...')


app = Starlette(
    debug=True,
    routes=[Route('/', index_view)],
    middleware=[
        Middleware(StarceptionMiddleware),
        # other middleware go here
    ],
)

Integration with FastAPI

Attach StarceptionMiddleware middleware to your FastAPI application:

import typing

from fastapi import FastAPI, Request

from starception import StarceptionMiddleware

app = FastAPI(debug=True)
app.add_middleware(StarceptionMiddleware)  # must be the first one!


@app.route('/')
async def index_view(request: Request) -> typing.NoReturn:
    raise TypeError('Oops, something really went wrong...')

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')

Dark theme

Switch between light/dark themes using set_theme utility.

Currently, we use pygments for syntax highlighting, therefore theme must be set in the code. In future releases we may highlight code on client side, and then we can make Starception to follow your browser's theme.

from starception import set_theme

set_theme('dark')

Credentials

• Look and feel inspired by Phoenix Framework.