Overview — Aquilia Documentation
Comprehensive guide and documentation for Overview in the Aquilia framework. View API reference, examples, and implementation patterns.
Unified Storage / Overview Unified Storage Subsystem Aquilia provides an async-native, unified storage abstraction that decouples your file management logic from the underlying storage providers. Configure local, in-memory, or cloud backends once, and access them anywhere. Quick Example Configure your storage integrations and interact with your files. Note that unlike legacy frameworks, you access backend instances from the registered StorageRegistry . from aquilia.storage import StorageRegistry from aquilia.storage.backends import LocalStorage, S3Storage from aquilia.storage.configs import LocalConfig, S3Config # Setup registry and backends manually (or let Workspace do it) registry = StorageRegistry() registry.register("local", LocalStorage(LocalConfig(root="./storage"))) registry.register("s3", S3Storage(S3Config(bucket="my-bucket", region="us-east-1"))) registry.set_default("local") # Save a file using the default backend (returns actual saved filename string) saved_path = await registry.default.save("docs/invoice.pdf", b"PDF_DATA") # Open a file as an async stream (returns a StorageFile wrapper) async with await registry.default.open("docs/invoice.pdf") as file: content = await file.read() # materialises the whole payload # Preferred for large objects: iterate, keeping memory bounded to one chunk async with await registry.default.open("backups/db.tar.gz") as file: async for chunk in file: await sink.write(chunk) # Save/access from a specific non-default backend await registry["s3"].save("backups/db.tar.gz", b"TAR_DATA") print(await registry["s3"].exists("backups/db.tar.gz")) Improved in 1.3.4 — real streaming, multipart uploads, dedicated pool The local and S3 backends previously loaded whole objects into memory on open() despite documenting a streaming contract, which risked out-of-memory failures on large files. They now stream in chunks; content materialises only if you call read() explicitly. Backends that stream also stream on save() and copy(). S3 uploads above multipart_threshold now use multipart, so objects larger than the 5 GB single-request limit succeed and peak memory stays near one part. A failed part aborts the upload rather than leaving an incomplete one behind. All blocking SDK calls run on a dedicated bounded thread pool with aquilia-storage threads instead of the interpreter's shared default executor, so storage I/O no longer competes with unrelated work. Size it with AQUILIA_STORAGE_MAX_WORKERS (default min(32, cpu_count + 4)). Subsystem Features ))} Supported Storage Backends Backend Class Description Library Dependency ))} Architecture STORAGEREGISTRY registry.default Routes alias to backend driver LOCALSTORAGE root: "./uploads" Writes to host filesystem S3STORAGE bucket: "my-bucket" AWS S3 / R2 Cloud Object MEMORYSTORAGE backends: dict Ephemeral RAM storage SFTPSTORAGE host: "remote.com" Remote SSH Transfer )
Go to Homepage