Skip to main content

FileFn Python SDK

The FileFn Python SDK is a powerful library for implementing robust file management capabilities in your Python applications. It provides a complete "backend-in-a-box" for handling file uploads, storage abstraction, metadata management, processing pipelines (like image thumbnails), and secure sharing.

Designed to integrate seamlessly with the Superfunctions ecosystem, it delegates persistence and storage to pluggable adapters.

Features

  • Chunked & Resumable Uploads: Built-in support for creating upload sessions, handling multi-part uploads, and verifying completion.
  • Storage Abstraction: Works with any StorageAdapter (S3, GCS, Azure, Local, etc.) provided by Superfunctions.
  • File Processing: Extensible processing pipeline. Includes a built-in Thumbnail Processor for on-the-fly image resizing.
  • Deduplication: Optional content-addressable storage logic to avoid storing duplicate files.
  • Security & Permissions:
    • Signed URLs: Secure upload and download links.
    • Grants System: Fine-grained permissions (read/write/delete/share) for users/tenants.
    • Policies: Define storage and access policies.
  • Sharing: Generate secure, expiring share links for public or restricted access.
  • Observability: Built-in event emitter for tracking file operations.

Installation

pip install filefn

Quick Start

The core of the library is the FileFn class, initialized via create_file_fn. You need to provide database and storage adapters.

1. Setup & Initialization

import asyncio
from filefn.server import create_file_fn, FileFnConfig
from filefn.processing.processors.thumbnail import create_thumbnail_processor, ThumbnailConfig

# Import adapters from your specific implementation or mocks
# from superfunctions.db.memory import MemoryAdapter
# from superfunctions.storage.local import LocalStorageAdapter

async def main():
    # 1. Initialize Adapters (Examples)
    # db_adapter = MemoryAdapter()
    # storage_adapter = LocalStorageAdapter(root_dir="./tmp_storage")

    # 2. Configure FileFn
    config = FileFnConfig(
        db=db_adapter,
        storage=storage_adapter,
        namespace="my-app-files",
        
        # Optional: Enable image thumbnail generation
        processing={
            "enabled": True,
            "processors": [
                create_thumbnail_processor(ThumbnailConfig(
                    format="jpeg",
                    quality=80,
                    sizes=[
                        {"name": "thumb", "width": 150, "height": 150},
                        {"name": "preview", "width": 800, "height": 600}
                    ]
                ))
            ]
        },
        
        # Security settings
        signed_url_ttl_seconds=3600, # 1 hour
    )

    # 3. Create the Service
    filefn = create_file_fn(config)

    # Now you can use filefn to manage files
    print("FileFn Service initialized!")

if __name__ == "__main__":
    asyncio.run(main())

2. Handling Uploads

FileFn uses a session-based approach for uploads (similar to S3 Multipart Uploads) to handle large files reliably.

# 1. Create an Upload Session
session_input = {
    "fileName": "vacation_photo.jpg",
    "mimeType": "image/jpeg",
    "size": 1024 * 1024 * 5, # 5MB
    "ownerId": "user_123",
    "policy": "default"
}
# ctx is a context object, usually containing request/auth info
ctx = {} 
session = await filefn.create_upload_session(session_input, ctx)
print(f"Session created: {session['uploadSessionId']}")

# 2. Client uploads parts using signed URLs provided in the session...
# (The client would PUT data to session['parts'][0]['url'], etc.)

# 3. Complete the Session (after client finishes uploading)
await filefn.complete_upload_session({
    "uploadSessionId": session['uploadSessionId']
}, ctx)

print("Upload complete & file created!")

3. Listing & Downloading

# List files for a specific owner
files = await filefn.list_files({
    "ownerId": "user_123",
    "limit": 20
}, ctx)

for f in files['items']:
    print(f"File: {f['name']} ({f['size']} bytes)")

# Get a download URL (Signed URL)
file_data = await filefn.get_file({"fileId": files['items'][0]['fileId']}, ctx)
print(f"Download URL: {file_data['downloadUrl']}")

Configuration Options

The FileFnConfig model accepts the following parameters:

Parameter Type Description
db Adapter Required. Database adapter instance.
storage StorageAdapter Required. Storage adapter instance.
namespace str Table prefix for database (default: 'filefn').
policies List[Policy] Custom storage/access policies.
processing Dict Configuration for file processing (thumbnails, etc.).
authorizer Authorizer Optional custom authorization logic.
quota QuotaProvider Optional quota management provider.
signed_url_ttl_seconds int TTL for generated signed URLs (default: 900).
upload_session_ttl_seconds int TTL for pending upload sessions (default: 86400).

Processors

Thumbnail Processor

Automatically generates image thumbnails upon upload completion.

from filefn.processing.processors.thumbnail import create_thumbnail_processor, ThumbnailConfig

processor = create_thumbnail_processor(ThumbnailConfig(
    sizes=[
        {"name": "small", "width": 100, "height": 100},
        {"name": "large", "width": 1024, "height": 1024}
    ],
    format="webp", # 'jpeg', 'png', 'webp'
    quality=90
))

Architecture

FileFn is built on a modular architecture:

  • Core Service (FileFn): Orchestrates all operations.
  • UploadSessionService: Manages the lifecycle of multipart uploads.
  • FileService: Handles file metadata (indexing, searching) and deletion.
  • ProcessingService: Runs background jobs (processors) on new files.
  • Adapters: Decouples the logic from specific infrastructure (DB/Storage).

This design allows FileFn to run on your local machine, in a serverless function, or a dedicated container with equal ease.

Metadata

Release files for filefn 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for filefn 0.1.0
File Size Uploaded Provenance Actions
filefn-0.1.0.tar.gz 21.9 kB Without provenance Details for filefn-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for filefn 0.1.0
File Interpreter ABI Platform Actions
filefn-0.1.0-py3-none-any.whl Python 3 none any Details for filefn-0.1.0-py3-none-any.whl

Total release size: 52.8 kB

Release files / filefn-0.1.0.tar.gz

Download URL filefn-0.1.0.tar.gz
Size 21.9 kB
Tags Source
SHA-256 checksum
How to use checksums
feaa41bec79cc664db98b1a31c939a06936603c0d6dc9a0e87ec5e294e9eae6c
BLAKE2b-256 checksum
How to use checksums
e8311acb9030dabd1e0b36ffc64243c15d1a0cae831653bb94ba20177b899ff5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / filefn-0.1.0-py3-none-any.whl

Download URL filefn-0.1.0-py3-none-any.whl
Size 30.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08fe2d3149c5f8ce7b10f3f290721d4d9b7b1b993c4f1c36ae49bfd2b4545804
BLAKE2b-256 checksum
How to use checksums
f075d336abff04a161dc8e74f51b610e6c5705fe5e1f1dd73968f42ea7aece53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for filefn 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page