opensanctions-pravda 0.1.0__tar.gz

opensanctions_pravda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSanctions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opensanctions_pravda-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: opensanctions-pravda
+Version: 0.1.0
+Summary: Durable web evidence capture with a remote browser, Postgres, and content-addressed storage
+Keywords: evidence,web-archiving,web-capture,playwright,har,forensics
+Author: OpenSanctions
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: alembic>=1.18.5
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: fsspec[gcs]>=2026.4.0
+Requires-Dist: playwright>=1.60.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.50
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/opensanctions/pravda
+Project-URL: Documentation, https://github.com/opensanctions/pravda#readme
+Project-URL: Repository, https://github.com/opensanctions/pravda
+Project-URL: Issues, https://github.com/opensanctions/pravda/issues
+Description-Content-Type: text/markdown
+
+# Pravda
+
+Pravda is a Python library for durable web evidence capture. It drives a
+remote Playwright browser to preserve rendered HTML, plaintext, full-page
+screenshots, metadata, and HAR recordings with response bodies. Snapshots are
+recorded in Postgres and on any fsspec-compatible backend for later inspection
+or comparison.
+
+Pravda is a **library, not a service**: it connects directly from the caller's
+process to the browser, database, and storage backend. Applications own that
+infrastructure (see [Infrastructure](#infrastructure)).
+
+- **Python** 3.13+
+- **Browser**: a remote Playwright Chromium WebSocket endpoint (headed Chrome
+  under xvfb). The browser is a client connection; Pravda does not launch one.
+- **Database**: PostgreSQL, upgraded to Pravda's schema with the
+  [migration helper](#database-migrations).
+- **Storage**: any fsspec URL (local path, `s3://`, `gs://`, …) for
+  content-addressed artifacts.
+
+## Installation
+
+```bash
+pip install opensanctions-pravda
+```
+
+## Quick start
+
+Construct a [`PravdaConfig`](#configuration), build a long-lived `Pravda`, and
+use it as an async context manager so its database engine is disposed on
+teardown. Reuse a single instance across captures — it owns the pooled engine,
+session factory, and storage backend, while each capture opens its own browser
+connection.
+
+```python
+from pravda import Pravda, PravdaConfig
+
+config = PravdaConfig(
+    database_url="postgresql+asyncpg://pravda:pravda@localhost:5432/pravda",
+    browser_ws_url="ws://localhost:3000",
+    storage_base_path="./data",
+)
+
+async def capture_example():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com")
+        print(snapshot.id, snapshot.http_status, snapshot.rendered_html)
+```
+
+## Configuration
+
+`PravdaConfig` takes three settings, supplied explicitly per instance:
+
+- `database_url` — async SQLAlchemy Postgres URL
+  (`postgresql+asyncpg://user:pass@host/db`).
+- `browser_ws_url` — remote Playwright WebSocket URL.
+- `storage_base_path` — fsspec storage URL, such as `./data`, `s3://bucket`,
+  or `gs://bucket`.
+
+## 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 complete pipeline is
+bounded by a wall-clock timeout:
+
+```python
+async def capture_example():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com")
+```
+
+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.
+
+```python
+async def drive(page, url):
+    await page.goto(url, wait_until="commit")
+    await page.wait_for_selector(".results")
+
+async def capture_results():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com", drive=drive)
+```
+
+`page` is a real `playwright.async_api.Page`, so selectors, clicks, form
+fills, and other Playwright operations are available. Playwright errors and
+timeouts from `drive` are persisted as failed snapshots. Other callback
+exceptions propagate and persist nothing.
+
+Chrome is configured to download PDFs instead of opening its viewer. In custom
+callbacks, `page.goto()` may therefore raise `Download is starting`; catch
+that Playwright error if the download is expected. Pravda recovers the
+downloaded body into the HAR.
+
+### Query history
+
+The configured instance returns all snapshots for an exact URL, newest first:
+
+```python
+async def print_history():
+    async with Pravda(config) as pravda:
+        history = await pravda.snapshots("https://example.com")
+        for snapshot in history:
+            print(snapshot.captured_at, snapshot.http_status)
+```
+
+## Database migrations
+
+Alembic owns the Pravda schema; the migration scripts ship inside the
+distribution. Bring a database up to the current schema head from application
+startup — the database URL is passed explicitly and **no** `DATABASE_URL`
+environment variable is required:
+
+```python
+import pravda
+
+async def setup():
+    await pravda.migrate("postgresql+asyncpg://user:pass@host/db")
+```
+
+`migrate()` runs the packaged revisions through Alembic (not
+`metadata.create_all`), is safe to call repeatedly (a database already at head
+is a no-op), works from inside a running event loop, and disposes the engine
+it creates. Database and migration failures propagate. There is no downgrade
+or automatic-startup behavior: call `migrate()` where and when you want the
+schema applied.
+
+## Storage
+
+Artifacts are content-addressed files under `Snapshot.prefix`. The `plaintext`,
+`rendered_html`, and `screenshot` fields contain filenames; HAR
+`response.content._file` fields refer to stored response bodies. Consumers
+read these files directly from the shared fsspec backend.
+
+## Infrastructure
+
+Applications own the external infrastructure Pravda talks to; Pravda does not
+launch or manage it:
+
+- **Browser** — a remote Playwright Chromium server exposed over WebSocket.
+  See the repository for a reference Docker image that runs headed Chrome under
+  xvfb and accepts launch options through the `x-playwright-launch-options`
+  WebSocket header.
+- **Postgres** — a database the application provisions and
+  [migrates](#database-migrations).
+- **Storage** — an fsspec backend the application points at via
+  `storage_base_path`.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) and Docker.
+
+```bash
+# Start the remote browser and Postgres
+docker compose up -d
+
+# Install dependencies
+uv sync
+
+# Validate
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+The migration scripts live inside the package at `pravda/migrations`. After
+changing models in `pravda/db.py`, the developer `alembic` command reads
+`DATABASE_URL` and points at the packaged scripts via `alembic.ini`:
+
+```bash
+DATABASE_URL=postgresql+asyncpg://pravda:pravda@localhost:5432/pravda \
+  uv run alembic upgrade head
+DATABASE_URL=postgresql+asyncpg://pravda:pravda@localhost:5432/pravda \
+  uv run alembic revision --autogenerate -m "describe the change"
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

opensanctions_pravda-0.1.0/README.md

@@ -0,0 +1,182 @@
+# Pravda
+
+Pravda is a Python library for durable web evidence capture. It drives a
+remote Playwright browser to preserve rendered HTML, plaintext, full-page
+screenshots, metadata, and HAR recordings with response bodies. Snapshots are
+recorded in Postgres and on any fsspec-compatible backend for later inspection
+or comparison.
+
+Pravda is a **library, not a service**: it connects directly from the caller's
+process to the browser, database, and storage backend. Applications own that
+infrastructure (see [Infrastructure](#infrastructure)).
+
+- **Python** 3.13+
+- **Browser**: a remote Playwright Chromium WebSocket endpoint (headed Chrome
+  under xvfb). The browser is a client connection; Pravda does not launch one.
+- **Database**: PostgreSQL, upgraded to Pravda's schema with the
+  [migration helper](#database-migrations).
+- **Storage**: any fsspec URL (local path, `s3://`, `gs://`, …) for
+  content-addressed artifacts.
+
+## Installation
+
+```bash
+pip install opensanctions-pravda
+```
+
+## Quick start
+
+Construct a [`PravdaConfig`](#configuration), build a long-lived `Pravda`, and
+use it as an async context manager so its database engine is disposed on
+teardown. Reuse a single instance across captures — it owns the pooled engine,
+session factory, and storage backend, while each capture opens its own browser
+connection.
+
+```python
+from pravda import Pravda, PravdaConfig
+
+config = PravdaConfig(
+    database_url="postgresql+asyncpg://pravda:pravda@localhost:5432/pravda",
+    browser_ws_url="ws://localhost:3000",
+    storage_base_path="./data",
+)
+
+async def capture_example():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com")
+        print(snapshot.id, snapshot.http_status, snapshot.rendered_html)
+```
+
+## Configuration
+
+`PravdaConfig` takes three settings, supplied explicitly per instance:
+
+- `database_url` — async SQLAlchemy Postgres URL
+  (`postgresql+asyncpg://user:pass@host/db`).
+- `browser_ws_url` — remote Playwright WebSocket URL.
+- `storage_base_path` — fsspec storage URL, such as `./data`, `s3://bucket`,
+  or `gs://bucket`.
+
+## 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 complete pipeline is
+bounded by a wall-clock timeout:
+
+```python
+async def capture_example():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com")
+```
+
+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.
+
+```python
+async def drive(page, url):
+    await page.goto(url, wait_until="commit")
+    await page.wait_for_selector(".results")
+
+async def capture_results():
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot("https://example.com", drive=drive)
+```
+
+`page` is a real `playwright.async_api.Page`, so selectors, clicks, form
+fills, and other Playwright operations are available. Playwright errors and
+timeouts from `drive` are persisted as failed snapshots. Other callback
+exceptions propagate and persist nothing.
+
+Chrome is configured to download PDFs instead of opening its viewer. In custom
+callbacks, `page.goto()` may therefore raise `Download is starting`; catch
+that Playwright error if the download is expected. Pravda recovers the
+downloaded body into the HAR.
+
+### Query history
+
+The configured instance returns all snapshots for an exact URL, newest first:
+
+```python
+async def print_history():
+    async with Pravda(config) as pravda:
+        history = await pravda.snapshots("https://example.com")
+        for snapshot in history:
+            print(snapshot.captured_at, snapshot.http_status)
+```
+
+## Database migrations
+
+Alembic owns the Pravda schema; the migration scripts ship inside the
+distribution. Bring a database up to the current schema head from application
+startup — the database URL is passed explicitly and **no** `DATABASE_URL`
+environment variable is required:
+
+```python
+import pravda
+
+async def setup():
+    await pravda.migrate("postgresql+asyncpg://user:pass@host/db")
+```
+
+`migrate()` runs the packaged revisions through Alembic (not
+`metadata.create_all`), is safe to call repeatedly (a database already at head
+is a no-op), works from inside a running event loop, and disposes the engine
+it creates. Database and migration failures propagate. There is no downgrade
+or automatic-startup behavior: call `migrate()` where and when you want the
+schema applied.
+
+## Storage
+
+Artifacts are content-addressed files under `Snapshot.prefix`. The `plaintext`,
+`rendered_html`, and `screenshot` fields contain filenames; HAR
+`response.content._file` fields refer to stored response bodies. Consumers
+read these files directly from the shared fsspec backend.
+
+## Infrastructure
+
+Applications own the external infrastructure Pravda talks to; Pravda does not
+launch or manage it:
+
+- **Browser** — a remote Playwright Chromium server exposed over WebSocket.
+  See the repository for a reference Docker image that runs headed Chrome under
+  xvfb and accepts launch options through the `x-playwright-launch-options`
+  WebSocket header.
+- **Postgres** — a database the application provisions and
+  [migrates](#database-migrations).
+- **Storage** — an fsspec backend the application points at via
+  `storage_base_path`.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) and Docker.
+
+```bash
+# Start the remote browser and Postgres
+docker compose up -d
+
+# Install dependencies
+uv sync
+
+# Validate
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+The migration scripts live inside the package at `pravda/migrations`. After
+changing models in `pravda/db.py`, the developer `alembic` command reads
+`DATABASE_URL` and points at the packaged scripts via `alembic.ini`:
+
+```bash
+DATABASE_URL=postgresql+asyncpg://pravda:pravda@localhost:5432/pravda \
+  uv run alembic upgrade head
+DATABASE_URL=postgresql+asyncpg://pravda:pravda@localhost:5432/pravda \
+  uv run alembic revision --autogenerate -m "describe the change"
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

opensanctions_pravda-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "opensanctions-pravda"
+version = "0.1.0"
+description = "Durable web evidence capture with a remote browser, Postgres, and content-addressed storage"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "OpenSanctions" }]
+keywords = [
+    "evidence",
+    "web-archiving",
+    "web-capture",
+    "playwright",
+    "har",
+    "forensics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "alembic>=1.18.5",
+    "asyncpg>=0.31.0",
+    "beautifulsoup4>=4.15.0",
+    "fsspec[gcs]>=2026.4.0",
+    "playwright>=1.60.0",
+    "sqlalchemy[asyncio]>=2.0.50",
+]
+
+[project.urls]
+Homepage = "https://github.com/opensanctions/pravda"
+Documentation = "https://github.com/opensanctions/pravda#readme"
+Repository = "https://github.com/opensanctions/pravda"
+Issues = "https://github.com/opensanctions/pravda/issues"
+
+[tool.uv.build-backend]
+module-name = "pravda"
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.15.16",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

opensanctions_pravda-0.1.0/src/pravda/__init__.py

@@ -0,0 +1,32 @@
+"""Durable evidence capture for web pages.
+
+Construct a :class:`Pravda` with explicit :class:`PravdaConfig` settings::
+
+    from pravda import Pravda, PravdaConfig
+
+    config = PravdaConfig(
+        database_url=...,
+        browser_ws_url=...,
+        storage_base_path=...,
+    )
+    async with Pravda(config) as pravda:
+        snapshot = await pravda.snapshot(url)
+        history = await pravda.snapshots(url)
+
+Applications own the Postgres database; bring it to the packaged schema head
+from startup with the migration helper::
+
+    import pravda
+    await pravda.migrate(database_url)
+"""
+
+from pravda.migrate import migrate
+from pravda.pravda import Pravda, PravdaConfig
+from pravda.snapshots import Snapshot
+
+__all__ = [
+    "Pravda",
+    "PravdaConfig",
+    "Snapshot",
+    "migrate",
+]