Debian Codegraph @

docs/usage/static-files.rst

raw
1 Static files
2 ============
3
4 To serve static files (i.e., serve arbitrary files from a given directory), the
5 :func:`~litestar.static_files.create_static_files_router` can be used to create a
6 :class:`Router <litestar.router.Router>` to handle this task.
7
8 .. literalinclude:: /examples/static_files/full_example.py
9 :language: python
10 :caption: Serving static files using :func:`create_static_files_router <litestar.static_files.create_static_files_router>`
11
12 In this example, files from the directory ``assets`` will be served on the path
13 ``/static``. A file ``assets/hello.txt`` would now be available on ``/static/hello.txt``
14
15 .. attention:: Directories are interpreted as relative to the working directory from which the
16 application is started
17
18 Sending files as attachments
19 ----------------------------
20
21 By default, files are sent "inline", meaning they will have a
22 ``Content-Disposition: inline`` header.
23
24 Setting :paramref:`~litestar.static_files.create_static_files_router.params.send_as_attachment` to ``True`` will send
25 them with a ``Content-Disposition: attachment`` instead:
26
27 .. literalinclude:: /examples/static_files/send_as_attachment.py
28 :language: python
29 :caption: Sending files as attachments using the the
30 :paramref:`~litestar.static_files.create_static_files_router.params.send_as_attachment` parameter
31 of :func:`create_static_files_router`
32
33 HTML mode
34 ---------
35
36 "HTML mode" can be enabled by setting :paramref:`~litestar.static_files.create_static_files_router.params.html_mode`
37 to ``True``.
38
39 This will:
40
41 - Serve and ``/index.html`` when the path ``/`` is requested
42 - Attempt to serve ``/404.html`` when a requested file is not found
43
44 .. literalinclude:: /examples/static_files/html_mode.py
45 :language: python
46 :caption: Serving HTML files using the :paramref:`~litestar.static_files.create_static_files_router.params.html_mode`
47 parameter of :func:`create_static_files_router`
48
49 Passing options to the generated router
50 ---------------------------------------
51
52 Options available on :class:`~litestar.router.Router` can be passed to directly
53 :func:`~litestar.static_files.create_static_files_router`:
54
55 .. literalinclude:: /examples/static_files/passing_options.py
56 :language: python
57 :caption: Passing options to the router generated by
58 :func:`create_static_files_router`
59
60 Using a custom router class
61 ---------------------------
62
63 The router class used can be customized with the
64 :paramref:`~.static_files.create_static_files_router.params.router_class` parameter:
65
66 .. literalinclude:: /examples/static_files/custom_router.py
67 :language: python
68 :caption: Using a custom router class with
69 :func:`create_static_files_router`
70
71 Retrieving paths to static files
72 --------------------------------
73
74 :meth:`~litestar.app.Litestar.route_reverse` and
75 :meth:`~litestar.connection.ASGIConnection.url_for` can be used to retrieve the path
76 under which a specific file will be available:
77
78 .. literalinclude:: /examples/static_files/route_reverse.py
79 :language: python
80 :caption: Retrieving paths to static files using :meth:`~.app.Litestar.route_reverse`
81
82 .. tip:: The ``name`` parameter has to match the ``name`` parameter passed to
83 :func:`create_static_files_router`, which defaults to ``static``.
84
85 (Remote) file systems
86 ---------------------
87
88 To customize how Litestar interacts with the file system, a class implementing the
89 :class:`~litestar.types.FileSystemProtocol` can be passed to ``file_system``. An example
90 of this are the file systems provided by
91 `fsspec <https://filesystem-spec.readthedocs.io/en/latest/>`_, which includes support
92 for FTP, SFTP, Hadoop, SMB, GitHub and
93 `many more <https://filesystem-spec.readthedocs.io/en/latest/api.html#implementations>`_,
94 with support for popular cloud providers available via 3rd party implementations such as
95
96 - S3 via `S3FS <https://s3fs.readthedocs.io/en/latest/>`_
97 - Google Cloud Storage via `GCSFS <https://gcsfs.readthedocs.io/en/latest/>`_
98 - Azure Blob Storage via `adlfs <https://github.com/fsspec/adlfs>`_
99
100 .. literalinclude:: /examples/static_files/file_system.py
101 :language: python
102 :caption: Using a custom file system with
103 :func:`create_static_files_router`
104
105 Upgrading from legacy StaticFilesConfig
106 ---------------------------------------
107
108 .. deprecated:: v3.0
109 :class:`StaticFilesConfig` is deprecated and will be removed in Litestar 3.0
110
111 Existing code can be upgraded to :func:`create_static_files_router` by replacing
112 :class:`StaticFilesConfig` instances with this function call and passing the result to
113 ``route_handlers`` instead of ``static_files_config``:
114
115 .. literalinclude:: /examples/static_files/upgrade_from_static_1.py
116 :language: python
117 :caption: Using the deprecated :class:`~.static_files.config.StaticFilesConfig`
118
119 .. literalinclude:: /examples/static_files/upgrade_from_static_2.py
120 :language: python
121 :caption: Upgrading from :class:`~.static_files.config.StaticFilesConfig` to
122 :func:`create_static_files_router`