Pravda
Pravda is a Python library for durable web evidence capture. It drives a remote Playwright browser to preserve rendered HTML, full-page screenshots, standalone HTML, metadata, and HAR recordings with response bodies. Snapshots are recorded in a SQL database (PostgreSQL or SQLite) and on any fsspec-compatible backend for later inspection or comparison.
Applications own the browser, database, and storage backend.
- Browser: a remote Playwright Chromium WebSocket endpoint (e.g. headed Chrome under xvfb).
- Database: PostgreSQL or SQLite.
- Storage: any fsspec URL (local path,
s3://,gs://, …) for content-addressed artifacts.
Installation
Python 3.12+
pip install opensanctions-pravda
Quick start
The application owns the SQLAlchemy engine and an async_sessionmaker;
construct a
PravdaConfig for the remaining settings and build a
long-lived Pravda. Reuse a single instance across captures — each capture
opens its own browser connection and database session — and dispose the engine
on shutdown.
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from pravda import Pravda, PravdaConfig
engine = create_async_engine("postgresql+psycopg://pravda:pravda@localhost:5432/pravda")
sessionmaker = async_sessionmaker(engine)
config = PravdaConfig(
browser_ws_url="ws://localhost:3000",
storage_base_path="./data",
)
async def capture_example():
pravda = Pravda(config, sessionmaker)
snapshot = await pravda.snapshot("https://example.com")
print(snapshot.id, snapshot.http_status, snapshot.rendered_html)
Configuration
browser_ws_url— remote Playwright WebSocket URL.storage_base_path— fsspec storage URL, such as./data,s3://bucket, orgs://bucket.timeouts— a frozenTimeoutsof wall-clock budgets for the captured website, defaulting to sensible values; see its docstring for what each budget does on expiry. Override individual fields withdataclasses.replace(Timeouts(), load=60).liveness— a frozenLivenessof deadlines for Pravda's own browser machinery.setupbounds connecting and preparing the recording context;closebounds closing it, which finalizes the recording. Both are seconds, default 30.
Usage
Capture a page
By default, Pravda navigates to the URL, waits for the normal load state,
captures the evidence, and persists the result. The target-facing capture is
bounded by one wall-clock budget; a wedged-but-alive storage backend or
database hangs until the caller cancels. Browser machinery — connecting,
preparing, or closing the recording context — is Pravda's infrastructure,
not the target: its failures raise InfrastructureError and persist
nothing, with a wedged-but-alive endpoint failing at the liveness
deadlines.
For custom navigation or interaction, pass an async drive(page, url)
callback. The callback owns the initial navigation; Pravda owns capture,
persistence, and cleanup, and records the state it leaves behind.
async def drive(page, url):
await page.goto(url, wait_until="commit")
await page.wait_for_selector(".results")
async def capture_results():
pravda = Pravda(config, sessionmaker)
snapshot = await pravda.snapshot("https://example.com", drive=drive)
page is a real playwright.async_api.Page. Playwright errors and timeouts
from drive are persisted as failed snapshots. Other callback exceptions
propagate and persist nothing.
When the browser endpoint sends PDFs as downloads, page.goto() in custom
callbacks may raise Download is starting; catch that Playwright error if
the download is expected. Pravda recovers the downloaded body into the HAR.
Storage
Artifacts are content-addressed files organized under the captured page's
hostname. The public Snapshot resolves its artifact fields to full storage
paths: rendered_html, screenshot, and standalone_html point at stored
files, and each HAR response.content._file resolves to its stored response
body. standalone_html is a self-contained rendering of the page —
stylesheets inlined, images embedded as data URIs, active content sanitized —
derived from the rendered DOM and the recorded HAR bodies for direct
inspection; derivation failures drop only that artifact.
Persisted database fields and HAR values keep their relative, content-addressed
names; consumers read the resolved paths directly from the shared fsspec
backend. Other storage failures propagate, and no snapshot record is
persisted.
Development
Requires uv and a remote Playwright browser
endpoint. Tests run against an in-memory SQLite database, so no database
service is needed. Environment variables live in .env; uv does not read
it automatically:
# Install dependencies
uv sync
# Local environment (once)
cp .env.example .env
# Validate
uv run --env-file .env pytest
uv run ruff check .
uv run ruff format --check .
License
MIT — see LICENSE.
Metadata
Release files for opensanctions-pravda 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| opensanctions_pravda-0.7.0.tar.gz | 13.5 kB | With provenance | Details for opensanctions_pravda-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| opensanctions_pravda-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for opensanctions_pravda-0.7.0-py3-none-any.whl |
Total release size: 30.3 kB
Release files / opensanctions_pravda-0.7.0.tar.gz
| Download URL | opensanctions_pravda-0.7.0.tar.gz |
|---|---|
| Size | 13.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f76992ebf67ffe5b1524fc6885ae49569b45d0a928631e4449a3735df03df2eb
|
|
BLAKE2b-256 checksum How to use checksums |
df97935b346e288e364e99030654966aeaf264b1f787188a96697ce64a5efb9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
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 Oct 20, 2026.
Transparency logRelease files / opensanctions_pravda-0.7.0-py3-none-any.whl
| Download URL | opensanctions_pravda-0.7.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8efaa29083b7ff4a07be598a1f45230b3ca3b94fdfbb9e4113f761892f5be695
|
|
BLAKE2b-256 checksum How to use checksums |
06c60008f5353dbfc43c71a63d5da77ca3febd2c0a98c3af5c67afbd3d3b59a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
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 Oct 20, 2026.
Transparency logSecurity for opensanctions-pravda 0.7.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.
Attestation for opensanctions_pravda-0.7.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 Oct 20, 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.