Ushka

API reference

ushka.static.files

Static file serving: the [static] directory and any number of mounts.

Files are served with an ETag and Last-Modified so browsers and CDNs revalidate cheaply (304 Not Modified), a configurable Cache-Control and X-Content-Type-Options: nosniff. Every path goes through ushka.guard.safe.path, so traversal, symlink escapes and null bytes are refused before the filesystem is touched.

def get_static_absolute_path(workdir: Path, static_dir: Path) -> Path

Resolves static_dir against workdir unless it is already absolute.

def file_response(path: Path, request: 'Request | None' = None, cache_control: str = DEFAULT_CACHE_CONTROL) -> Response

Builds the response for one file, answering 304 when it is unchanged.

Parameters

pathPath

A file that has already been validated (e.g. with safe.path).

requestRequest

Used for If-None-Match revalidation.

cache_controlstr

Value of the Cache-Control header. Use something like "public, max-age=31536000, immutable" for fingerprinted assets.

def resolve_in(root: Path, filename: str, html: bool = False) -> Path | None

Finds the file filename names inside root, or None.

With html=True a directory resolves to its index.html (the layout static site generators such as MkDocs produce).

def server_static_files(filename: str, config: Config, request: 'Request') -> Response

Serves a file from the [static] directory (registered when enabled).