What's the purpose of having multiple directories per static route?

[smac89]

I'm just trying to understand the reasoning behind multiple directories for a static route handler. Does the router search through all the directories to find the one being requested? If so, what happens when the same name is found in more than one directory?

create_static_files_router(
  "/static",
  directories=['/var/www', '/var/cache'],
  send_as_attachment=True,
)

[sinisaos]

@smac89 That's a good point. And I also do not understand what is the purpose of multiple directories per static route because if we have the same file name in multiple directories, only file from first matching directory will be displayed, ignoring the others.

Example with multiple static directories

from pathlib import Path

from litestar import Litestar
from litestar.static_files import create_static_files_router

ASSETS_DIR = Path("assets")
STATIC_DIR = Path("static")


def on_startup():
    ASSETS_DIR.mkdir(exist_ok=True)
    ASSETS_DIR.joinpath("hello.txt").write_text("Hello, assets!")
    STATIC_DIR.mkdir(exist_ok=True)
    STATIC_DIR.joinpath("hello.txt").write_text("Hello, static!")


app = Litestar(
    debug=True,
    route_handlers=[
        create_static_files_router(
            path="/static",
            directories=["assets", "static"],
        ),
    ],
    on_startup=[on_startup],
)

Result is (we cannot get the contents of the file STATIC_DIR hello.txt):

> curl http://127.0.0.1:8000/static/hello.txt
Hello, assets!

We can have one static directory (like other frameworks do) that can have subdirectories. We can have the same files in those subdirectories that display correctly. Something like this

Example with single static directory with subdirectories

from pathlib import Path

from litestar import Litestar
from litestar.static_files import create_static_files_router

ASSETS_DIR = Path("assets")
FIRST = Path("assets/first")
SECOND = Path("assets/second")


def on_startup():
    ASSETS_DIR.mkdir(exist_ok=True)
    FIRST.mkdir(exist_ok=True)
    SECOND.mkdir(exist_ok=True)
    FIRST.joinpath("hello.txt").write_text("Hello, first!")
    SECOND.joinpath("hello.txt").write_text("Hello, second!")


app = Litestar(
    debug=True,
    route_handlers=[
        create_static_files_router(
            path="/static",
            directories=["assets"],
        ),
    ],
    on_startup=[on_startup],
)

Result is:

> curl http://127.0.0.1:8000/static/first/hello.txt
Hello, first! 
> curl http://127.0.0.1:8000/static/second/hello.txt
Hello, second!

I'm sorry if I missed the point. Maybe someone from the Litestar team has a better explanation and use case for using multiple directories for a static route handler.

[sfermigier]

IIUC, the StaticFiles class tries to resolve the file in the given directories, in the given order. This way, you should be able to implement simple overlay mechanisms with the framework's support.