Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

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.2

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

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for calmlens 0.27.2
File Size Uploaded Provenance Actions
calmlens-0.27.2.tar.gz 198.5 kB With provenance Details for calmlens-0.27.2.tar.gz

Built distribution (wheel)

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

Total release size: 347.9 kB

Release files / calmlens-0.27.2.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL calmlens-0.27.2.tar.gz
Size 198.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f5aaa8b8e08a868518679352b8380713be4654dbaf42da2f994b486124a09b6c
BLAKE2b-256 checksum
How to use checksums
ce89603ac9044432620eed399c69bb472c0e11a209621a4d580ee57326ea5481
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 18, 2026.

Transparency log

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

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL calmlens-0.27.2-py3-none-any.whl
Size 149.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ab55a79e41004ce0203c5232fd375d186b7e59b49b7aab05136ab8cfe159b3e7
BLAKE2b-256 checksum
How to use checksums
cb27393c9807d1fed5616ca28073fde20672aa4e02de6278fd8ce846f44cf739
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 18, 2026.

Transparency log

Security for calmlens 0.27.2

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.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Repository

Select from 2 files

Attestation for calmlens-0.27.2.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 18, 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