Usage

Installation

uv add schlepper

Or with pip:

pip install schlepper

Basic usage

Create an ApiToken (or ApiKey) and call deploy() with the directory you want to publish:

import schlepper

result = schlepper.deploy(
    "./dist",
    project_name="my-site",
    account_id="your-account-id",
    credentials=schlepper.ApiToken(token="your-api-token"),
    branch="production",
    commit_message="Deploy v1.0.0",
)

print(f"Deployed to {result.url} (status: {result.status})")

deploy() handles the full lifecycle: validating the directory, hashing and uploading assets, creating the deployment, and polling until it reaches a terminal state. It returns a Deployment with the result.

Authentication

Cloudflare supports two credential types:

API Token (recommended) — a scoped token created in the Cloudflare dashboard:

credentials = schlepper.ApiToken(token="your-api-token")

Global API Key — the legacy key plus your account email:

credentials = schlepper.ApiKey(key="your-global-api-key", email="you@example.com")

Commit metadata

You can attach git metadata to each deployment:

result = schlepper.deploy(
    "./dist",
    project_name="my-site",
    account_id="your-account-id",
    credentials=credentials,
    branch="production",
    commit_hash="abc1234",
    commit_message="Fix homepage layout",
    commit_dirty=False,
)

Special files

Cloudflare Pages recognises several special files in the deploy directory:

• _headers — custom HTTP response headers

• _redirects — URL redirect rules

• _routes.json — custom routing configuration

These files are not uploaded as static assets. Instead, schlepper sends them as metadata alongside the deployment so that Cloudflare can process them as configuration.

Error handling

All errors raised by schlepper are subclasses of SchlepperError:

try:
    result = schlepper.deploy(...)
except schlepper.ValidationError:
    # Directory validation failed (too many files, file too large, etc.)
    ...
except schlepper.AuthenticationError:
    # Invalid or missing credentials
    ...
except schlepper.UploadError:
    # Asset upload failed after retries
    ...
except schlepper.DeploymentError:
    # Deployment creation or polling failed
    ...
except schlepper.APIError as e:
    # Cloudflare API returned an error
    print(f"HTTP {e.status}: {e}")
    ...