Granite Assets Documentation
Granite Assets is a portable, backend-agnostic asset repository abstraction
for Python applications. It provides a single, typed IAssetRepository interface
with two ready-made implementations — local filesystem (Nginx-served) and AWS S3 —
so you can swap storage backends without touching application code.
Key Features
Protocol-based contract — implement
IAssetRepositorywithout inheriting from any base class.Local + S3 backends — production-ready implementations included.
Resumable uploads (tus) —
LocalNginxAssetRepositorygenerates tus creation URLs for a tusd server, supporting arbitrarily large files and resume on failure.Presigned S3 upload URLs —
S3AssetRepositorygenerates presignedPUTURLs for direct browser-to-S3 uploads.Signed download URLs —
LocalNginxAssetRepositorysupports Nginxsecure_linktokens;S3AssetRepositorygenerates presignedGETURLs.Public URL support — stable, permanent URLs for public assets via CDN or Nginx.
Asset descriptors — lightweight metadata queries (
HEAD-like) without downloading content.Copy / move — cheap server-side operations that avoid unnecessary data transfer.
Typed — full type hints;
py.typedmarker included.Extensible — add any new backend by implementing the
IAssetRepositoryprotocol.
Quick Start
Installation:
pip install granite-assets
Local filesystem example:
from granite_assets import (
LocalNginxAssetRepositoryConfig,
LocalNginxAssetRepository,
AssetSaveRequest,
AssetVisibility,
)
config = LocalNginxAssetRepositoryConfig(
storage_path="/var/www/assets",
base_url="https://cdn.example.com/assets",
)
repo = LocalNginxAssetRepository(config)
request = AssetSaveRequest(
key="avatars/user-42.jpg",
source=open("photo.jpg", "rb"),
content_type="image/jpeg",
visibility=AssetVisibility.PUBLIC,
)
result = repo.save(request)
url = repo.build_public_url(result.key)
print(url.url) # https://cdn.example.com/assets/public/avatars/user-42.jpg
Contents
Getting Started
Developer Guide