static_files#

class litestar.static_files.StaticFiles#

Bases: object

ASGI App that handles file sending.

__init__(is_html_mode: bool, directories: Sequence[PathType], file_system: FileSystemProtocol, send_as_attachment: bool = False, resolve_symlinks: bool = True, headers: dict[str, str] | None = None) → None#

Initialize the Application.

Parameters:

  • is_html_mode – Flag dictating whether serving html. If true, the default file will be index.html.

  • directories – A list of directories to serve files from.

  • file_system – The file_system spec to use for serving files.

  • send_as_attachment – Whether to send the file with a content-disposition header of attachment or inline

  • resolve_symlinks – Resolve symlinks to the directories

  • headers – Headers that will be sent with every response.

async get_fs_info(directories: Sequence[PathType], file_path: PathType) → tuple[Path, FileInfo] | tuple[None, None]#

Return the resolved path and a stat_result.

Changed in version 2.8.3: Prevent CVE-2024-32982 by ensuring that the resolved path is within the configured directory as part of advisory GHSA-83pv-qr33-2vcf.

Parameters:

  • directories – A list of directory paths.

  • file_path – A file path to resolve

Returns:

A tuple with an optional resolved Path instance and an optional stat_result.

async __call__(scope: Scope, receive: Receive, send: Send) → None#

ASGI callable.

Parameters:

  • scope – ASGI scope

  • receive – ASGI receive callable

  • send – ASGI send callable

Returns:

None

class litestar.static_files.StaticFilesConfig#

Bases: object

Configuration for static file service.

To enable static files, pass an instance of this class to the Litestar constructor using the ‘static_files_config’ key.

path: str#

Path to serve static files from.

Note that the path cannot contain path parameters.

directories: list[PathType]#

A list of directories to serve files from.

html_mode: bool = False#

Flag dictating whether serving html.

If true, the default file will be ‘index.html’.

name: str | None = None#

An optional string identifying the static files handler.

file_system: Any = <litestar.file_system.BaseLocalFileSystem object>#

The file_system spec to use for serving files.

Notes

opt: dict[str, Any] | None = None#

A string key dictionary of arbitrary values that will be added to the static files handler.

__init__(path: str, directories: list[PathType], html_mode: bool = False, name: str | None = None, file_system: Any = <litestar.file_system.BaseLocalFileSystem object>, opt: dict[str, Any] | None = None, guards: list[Guard] | None = None, exception_handlers: ExceptionHandlersMap | None = None, send_as_attachment: bool = False) → None#
guards: list[Guard] | None = None#

A list of Guard callables.

exception_handlers: ExceptionHandlersMap | None = None#

A dictionary that maps handler functions to status codes and/or exception types.

send_as_attachment: bool = False#

Whether to send the file as an attachment.

to_static_files_app() → ASGIRouteHandler#

Return an ASGI app serving static files based on the config.

Returns:

StaticFiles

litestar.static_files.create_static_files_router(path: str, directories: list[PathType], file_system: Any = None, send_as_attachment: bool = False, html_mode: bool = False, name: str = 'static', after_request: AfterRequestHookHandler | None = None, after_response: AfterResponseHookHandler | None = None, before_request: BeforeRequestHookHandler | None = None, cache_control: CacheControlHeader | None = None, exception_handlers: ExceptionHandlersMap | None = None, guards: list[Guard] | None = None, include_in_schema: bool | EmptyType = False, middleware: Sequence[Middleware] | None = None, opt: dict[str, Any] | None = None, security: Sequence[SecurityRequirement] | None = None, tags: Sequence[str] | None = None, router_class: type[Router] = <class 'litestar.router.Router'>, resolve_symlinks: bool = True) → Router#

Create a router with handlers to serve static files.

Parameters:

  • path – Path to serve static files under

  • directories – Directories to serve static files from

  • file_system – A file system implementing FileSystemProtocol. fsspec can be passed here as well

  • send_as_attachment – Whether to send the file as an attachment

  • html_mode – When in HTML: - Serve an index.html file from / - Serve 404.html when a file could not be found

  • name – Name to pass to the generated handlers

  • after_request – after_request handlers passed to the router

  • after_response – after_response handlers passed to the router

  • before_request – before_request handlers passed to the router

  • cache_control – cache_control passed to the router

  • exception_handlers – Exception handlers passed to the router

  • guards – Guards passed to the router

  • include_in_schema – Include the routes / router in the OpenAPI schema

  • middleware – Middlewares passed to the router

  • opt – Opts passed to the router

  • security – Security options passed to the router

  • tags – tags passed to the router

  • router_class – The class used to construct a router from

  • resolve_symlinks – Resolve symlinks of directories