# 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 `IAssetRepository` without inheriting from any base class.

- Local + S3 backends — production-ready implementations included.

- Resumable uploads (tus) — `LocalNginxAssetRepository` generates tus creation URLs for a tusd server, supporting arbitrarily large files and resume on failure.

- Presigned S3 upload URLs — `S3AssetRepository` generates presigned `PUT` URLs for direct browser-to-S3 uploads.

- Signed download URLs — `LocalNginxAssetRepository` supports Nginx `secure_link` tokens; `S3AssetRepository` generates presigned `GET` URLs.

- 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.typed` marker included.

- Extensible — add any new backend by implementing the `IAssetRepository` protocol.

# 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

- Installation
  - Requirements
  - Package Installation
  - Development Installation
  - S3 Extra
  - Type Checking
- Quick Start
  - Local Filesystem (Nginx)
  - AWS S3
  - Using the Factory
  - Error Handling

User Guide

- User Guide
  - Architecture Overview
  - Key Concepts
  - Saving Assets
  - Reading Asset Metadata
  - Copy and Move
  - Deleting Assets
  - FastAPI Integration
  - Local Nginx Backend Details
  - S3 Backend Details
- Upload and Download URLs
  - Upload URLs
  - Download URLs
  - Security Considerations
- Infrastructure Setup
  - Local Setup: Nginx + tusd
  - AWS Setup: S3 + CloudFront

Developer Guide

- Implementing a Custom Repository
  - The Interface
  - Example: Azure Blob Storage Backend
  - Implementation Checklist

API Reference

- API Reference
  - granite_assets package
  - granite_assets.contracts
  - granite_assets.models
  - granite_assets.enums
  - granite_assets.exceptions
  - granite_assets.factory
  - granite_assets.repositories

# Indices and Tables

- Index

- Module Index

- Search Page