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), with a synchronous client and an asynchronous one.

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.decision == "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)
print(decided.last_response.request_id)

Methods take snake_case keyword arguments, and dict options (such as processing_options) take snake_case keys. Results are typed objects from calmlens.types, read through snake_case attributes (asset.classification.moderation.decision); to_dict() returns the API's JSON. Lists return a page you can iterate, with auto_paging_iter() for every page after it. Every method takes per-call options such as {"timeout": 10, "idempotency_key": "..."}. From asyncio, use AsyncCalmLensServerClient, which has the same methods, awaitable.

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

Status What to do
None 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.27.3

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.27.3
File Size Uploaded Provenance Actions
calmlens-0.27.3.tar.gz 198.4 kB With provenance Details for calmlens-0.27.3.tar.gz

Built distribution (wheel)

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

Total release size: 347.7 kB

Release files / calmlens-0.27.3.tar.gz

Download URL calmlens-0.27.3.tar.gz
Size 198.4 kB
Tags Source
SHA-256 checksum
How to use checksums
aad6a3ddea6d66702ecd19a018c6d507d55feac6fa2f4cc40a41660b3f543961
BLAKE2b-256 checksum
How to use checksums
dc4e4723c07a102836e6d4168d59f135d4fa9ee2eeba452ebeb252c52cd6a0c6
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 20, 2026.

Transparency log

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

Download URL calmlens-0.27.3-py3-none-any.whl
Size 149.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5acab22aa896df5cffd9528d38ba8a15c8f2e10cc0e53e7594c86ef8f1d98a8d
BLAKE2b-256 checksum
How to use checksums
4d2bc8cb443c30e9455e79864e5637e01e6e80d86d8524fd535cfe2833ebf836
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 20, 2026.

Transparency log

Security for calmlens 0.27.3

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.27.3.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 20, 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