Skip to main content

CalmLens Python SDK

Server-side Python SDK for CalmLens content moderation, storage and CDN delivery. It requires Python 3.10 or later, has no runtime dependencies and is fully typed (py.typed, checked with mypy --strict).

Install

python -m pip install calmlens

Versions follow semantic versioning: see Versioning and support.

Quick start

Create an API key and copy your project ID as described in Authentication. Keep both on your server.

from calmlens import CalmLensServerClient

# Reads CALMLENS_API_KEY and CALMLENS_PROJECT_ID from the environment when not passed.
client = CalmLensServerClient()

asset = client.text.classify(text="Great photo!", external_id="comment-42")
if asset["classification"]["moderation"]["status"] == "allowed":
    print("Allowed: safe to show")

with open("photo.jpg", "rb") as file:  # streamed, not read into memory
    queued = client.assets.create(name="photo.jpg", content={"data": file, "type": "image/jpeg"})

decided = client.assets.wait_for_decision(asset_id=queued["id"], timeout=30)

Methods take snake_case keyword arguments, or one options dict with the API's camelCase keys (client.assets.retrieve({"assetId": "..."})). Responses are plain dicts with the API's camelCase field names, typed as TypedDicts in calmlens.types.

assets.create returns without waiting for the decision; assets.classify and text.classify wait for it. Act on classification.moderation.status:

Status What to do
pending Moderation hasn't decided yet: wait, poll or handle a webhook.
allowed Show the content.
limited Show it with reduced reach: keep it out of recommendations and notifications.
age-restricted Show it only to viewers your app has age-checked.
blocked Don't show it. The content is kept for review.
purged Don't show it. The stored content has been deleted.

Treat a status you don't recognise, and a failed request, as not allowed.

What you can do

Testing

MockCalmLensServerClient from calmlens.testing is the real client with an in-memory API behind it, for offline tests. Its generate_test_text_code, paint_test_image and generate_media_test_code make signed test inputs that the real API answers with the scenario you choose, using your project's test input key. Submit a text code as the whole text and a test image as the whole upload. See Python testing.

Command-line tool

Use the standalone CalmLens CLI to forward signed webhook events to your machine and trigger test uploads.

Metadata

Release files for calmlens 0.25.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 calmlens 0.25.0
File Size Uploaded Provenance Actions
calmlens-0.25.0.tar.gz 172.6 kB With provenance Details for calmlens-0.25.0.tar.gz

Built distribution (wheel)

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

Total release size: 309.1 kB

Release files / calmlens-0.25.0.tar.gz

Download URL calmlens-0.25.0.tar.gz
Size 172.6 kB
Tags Source
SHA-256 checksum
How to use checksums
fa0e7f04a412218049de98cd4c3f3e104536a6bad44b6c2023ba22e7d633f805
BLAKE2b-256 checksum
How to use checksums
eefa3342b4fa536fbf735f7deb3f2b72d543061b44e19fd6c7cd77d28a313e00
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / calmlens-0.25.0-py3-none-any.whl

Download URL calmlens-0.25.0-py3-none-any.whl
Size 136.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e44d710a5070ef37412e2052e2f2d2a693e0f02aa0a7b03b0b739489d73b13f1
BLAKE2b-256 checksum
How to use checksums
cf4bfa34e75479e52db4b1735505b36533e0d70e3e5e2b126b106b1df2a0bec4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for calmlens 0.25.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for calmlens-0.25.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

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.

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