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
- Moderate text, images, audio and video and read the classification report.
- Stream uploads, including multipart uploads and uploads from a URL.
- Moderate replies with their conversation.
- Sign upload tokens for upload presets used from browsers.
- Manage assets: list, search, update, move, retry, page through an audio or video asset's findings timeline, record reviewer decisions and delete content.
- Organise assets in folders and compare uploads with hash lists.
- Manage the organisation's moderation policies and choose the one each project uses.
- Keep project configuration in code:
client.upload_presets(list,iter,ensure,delete),client.project_settings(get,update) andclient.metadata_fields(list,ensure,delete).ensurecreates or replaces upload presets by key and metadata fields by ID; send therevisionyou read to refuse a change made since. - Deliver content through the CDN with lenses and transforms, signed URLs and viewer claims.
- Verify and parse webhooks from Flask, Django or FastAPI, or poll the events feed.
- Handle errors with stable error codes and a class per
kind of failure, such as
CalmLensNotFoundErrorandCalmLensRateLimitError, and rely on safe retries and idempotency keys. - Configure the client: timeouts, proxies,
TLS settings, your own transport, logging (
CALMLENS_LOG), a hook for every attempt, connection reuse across threads and forked workers, and the async client.
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.
Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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
- Removed 0.25.0 github.com/CalmLens/CalmLens
- Added 0.27.2 github.com/CalmLens/sdks
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 logA 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.