Python integration

The official Python package for Fileboy. Upload files and video, build image transform URLs and read video data from Django or plain Python.

Installation

Install

fileboy

from PyPI. You need your public key from your app's keys page.

1
pip install fileboy

Quick start

1
2
3
4
5
6
7
8
9
import os
import fileboy

client = fileboy.Client(public_key=os.environ["FILEBOY_PUBLIC_KEY"])

file = client.upload_file("report.pdf")
print(file.id)  # store this

client.build_image_url(file.id, transforms=[{"type": "resize", "width": 300}])

Upload a file

Pass a path or an open file. The method returns the stored file's details. Save its id.

1
2
3
4
5
6
file = client.upload_file(
    "./exports/report.pdf",
    metadata={"customerId": "cus_123", "kind": "monthly-report"},
)

print(file.id)  # save this

Upload from a URL

Fileboy fetches the file itself, so it never passes through your server.

1
2
3
4
5
photo = client.upload_file_from_url(
    "https://example.com/photo.jpg",
    name="photo.jpg",
    expect="image/jpeg",
)

Build file and image URLs

URLs are built locally, with no request.

1
2
3
4
5
6
# the details of one file: name, mime, size, hash, metadata
data = client.fetch_file_data(file.id)

# a URL for a file or an image
link = client.build_file_url(file.id, download=True)
thumb = client.build_image_url(photo.id, transforms=[{"type": "resize", "width": 300}])

Resize images with a URL

Transforms run in the order you list them. The image service supports resize, format, quality, background and invert.

1
2
3
4
5
url = client.build_image_url(photo_id, transforms=[
    {"type": "resize", "width": 800},
    {"type": "format", "format": "webp"},
    {"type": "quality", "value": 80},
])

Videos

Videos are encoded in the background. Upload, then poll the video's data until it is ready.

1
2
3
4
5
6
7
8
video = client.upload_video("./clips/launch.mp4", name="Launch day")

# encoding runs in the background: poll until it is ready
data = client.fetch_video_data(video.id)
data["extractionStatus"]

client.build_video_manifest_url(video.id, type="hls")
client.build_video_poster_url(video.id)

Using it in Django

1
2
3
4
5
6
7
8
9
10
11
# settings.py
import os
import fileboy

fileboy.configure(public_key=os.environ["FILEBOY_PUBLIC_KEY"])

# views.py
def upload_avatar(request):
    upload = request.FILES["avatar"]
    file = fileboy.client().upload_file(upload.file, name=upload.name, mime=upload.content_type)
    request.user.avatar_id = file.id

Webhooks

Check that a webhook really came from Fileboy. Pass the raw request body, exactly as received. The webhooks reference lists every event.

1
2
3
4
5
6
7
event = fileboy.verify_webhook(
    request.body, request.headers, settings.FILEBOY_WEBHOOK_SECRET
)

if event["type"] == "video.ready":
    print(event["resource"]["urls"]["hls"])
# raises fileboy.WebhookVerificationError when the signature or timestamp is wrong

The package README lists every method, the error classes and the transform options. Every endpoint is also in the API reference and the OpenAPI spec.