| 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` |