Dependencies¶

Utilities for manual dependency injection when not using the StoragePlugin.

Type Alias¶

litestar_storages.contrib.dependencies.StorageDependency: TypeAlias¶

Type alias for storage dependency injection in route handlers.

from litestar import get
from litestar_storages.contrib.dependencies import StorageDependency

@get("/files/{key:str}")
async def get_file(key: str, storage: StorageDependency) -> bytes:
    return await storage.get_bytes(key)

Provider Function¶

litestar_storages.contrib.dependencies.provide_storage(storage)[source]¶

Create a dependency provider function for a storage instance.

This function can be used to create custom dependency providers for storage instances when not using the StoragePlugin.

Parameters:: storage (Storage) – The storage instance to provide
Return type:: Callable[[], Storage]
Returns:: A callable that returns the storage instance for dependency injection

Example

Manual dependency registration:

from litestar import Litestar
from litestar.di import Provide
from litestar_storages import S3Storage, S3Config
from litestar_storages.contrib.dependencies import provide_storage

storage = S3Storage(config=S3Config(bucket="uploads"))

app = Litestar(
    route_handlers=[...],
    dependencies={
        "storage": Provide(provide_storage(storage)),
    },
)

With multiple storages:

from litestar import Litestar
from litestar.di import Provide
from litestar_storages import S3Storage, AzureStorage
from litestar_storages.contrib.dependencies import provide_storage

s3 = S3Storage(config=S3Config(bucket="main"))
azure = AzureStorage(config=AzureConfig(container="archive"))

app = Litestar(
    route_handlers=[...],
    dependencies={
        "storage": Provide(provide_storage(s3)),
        "archive_storage": Provide(provide_storage(azure)),
    },
)

Usage Examples¶

Manual Dependency Registration¶

When you need more control over dependency registration than the plugin provides:

from litestar import Litestar
from litestar.di import Provide
from litestar_storages import S3Storage, S3Config
from litestar_storages.contrib.dependencies import provide_storage

storage = S3Storage(config=S3Config(bucket="uploads"))

app = Litestar(
    route_handlers=[...],
    dependencies={
        "storage": Provide(provide_storage(storage), sync_to_thread=False),
    },
)

Multiple Storages¶

from litestar import Litestar
from litestar.di import Provide
from litestar_storages import S3Storage, AzureStorage
from litestar_storages.contrib.dependencies import provide_storage

s3 = S3Storage(config=S3Config(bucket="main"))
azure = AzureStorage(config=AzureConfig(container="archive"))

app = Litestar(
    route_handlers=[...],
    dependencies={
        "storage": Provide(provide_storage(s3), sync_to_thread=False),
        "archive_storage": Provide(provide_storage(azure), sync_to_thread=False),
    },
)

With Manual Cleanup¶

When not using the plugin, you must handle cleanup manually:

from litestar import Litestar
from litestar.di import Provide
from litestar_storages import S3Storage, S3Config
from litestar_storages.contrib.dependencies import provide_storage

storage = S3Storage(config=S3Config(bucket="uploads"))

async def cleanup(app: Litestar) -> None:
    await storage.close()

app = Litestar(
    route_handlers=[...],
    dependencies={
        "storage": Provide(provide_storage(storage), sync_to_thread=False),
    },
    on_shutdown=[cleanup],
)

Router-Level Dependencies¶

from litestar import Router, get
from litestar.di import Provide
from litestar_storages import S3Storage, Storage
from litestar_storages.contrib.dependencies import provide_storage

@get("/")
async def list_uploads(storage: Storage) -> list[str]:
    return [f.key async for f in storage.list()]

uploads_router = Router(
    path="/uploads",
    route_handlers=[list_uploads],
    dependencies={
        "storage": Provide(
            provide_storage(S3Storage(config=S3Config(bucket="uploads"))),
            sync_to_thread=False,
        ),
    },
)

When to Use Manual Dependencies¶

Use manual dependency registration instead of the plugin when you need:

Router-specific storages - Different storages for different routers
Conditional registration - Logic determining which storage to use
Testing overrides - Easy swapping of storage in tests
Custom cleanup logic - Additional cleanup beyond close()

For most applications, StoragePlugin is simpler and handles lifecycle management automatically.