Figranium Python SDK
Official Python SDK for Figranium, the self-hosted browser automation and web scraping platform.
- Synchronous and asynchronous clients
- Type hints and a
py.typedmarker - API-key and persistent browser-session authentication
- Configurable timeouts, custom
httpxclients, structured errors, and SSE streams - Python 3.9+
Install
pip install figranium-sdk
Quick start
import os
from figranium import Figranium
with Figranium(
base_url="http://localhost:11345",
api_key=os.environ["FIGRANIUM_API_KEY"],
) as figranium:
tasks = figranium.tasks.list_summaries()["tasks"]
result = figranium.run_task(
tasks[0]["id"],
{
"variables": {"query": "Python SDK"},
},
)
print(result.get("data"))
print(result.get("outcome")) # success | error | stopped | crashed | anti_bot
base_url defaults to http://localhost:11345. API keys use Authorization: Bearer by default. Set api_key_header="x-api-key" if your deployment expects that header.
Create a typed task
from figranium import Figranium, Task, actions, variable
task: Task = {
"name": "Search and extract",
"description": "Runs a search and captures visible results",
"url": "https://example.com",
"mode": "agent",
"variables": {"query": {"type": "string", "value": "figranium"}},
"actions": [
actions.wait_for("#search"),
actions.type("#search", variable("query")),
actions.press("Enter", "#search"),
actions.wait_for(".results"),
actions.get_content(".results", "resultText"),
],
}
with Figranium(api_key="...") as client:
saved = client.tasks.save(task)
result = client.run_task(
saved["id"],
{
"variables": {"query": "browser automation"},
},
)
variable("query") produces Figranium's required {$query} syntax. Action helpers generate unique IDs and accept base={...} for common fields or a caller-supplied ID. Plain action dictionaries remain supported when every specification field is needed.
CAPTCHA-aware tasks can wait for a challenge and solve it separately:
actions.wait_for_captcha(
captcha_type="turnstile",
selector="#challenge",
timeout=120_000,
var_name="captchaReady",
)
actions.solve_captcha(captcha_type="turnstile", timeout=120_000)
Async client
Every resource is available through AsyncFigranium with the same method names:
from figranium import AsyncFigranium
async with AsyncFigranium(api_key="...") as client:
result = await client.run_task("task-id", {"variables": {"query": "async Python"}})
Stream executions
Synchronous streams are ordinary iterators:
with Figranium(api_key="...") as client:
for event in client.executions.stream():
print(event.get("event"), event["data"])
Asynchronous streams are async iterators:
async with AsyncFigranium(api_key="...") as client:
async for event in client.executions.stream():
print(event.get("event"), event["data"])
Streams remain open unless the server closes them, iteration stops, or an optional stream timeout is supplied with options={"timeout": 60}.
Error handling
from figranium import FigraniumError
try:
result = client.run_task("missing-task")
except FigraniumError as error:
print(error.status) # HTTP status, or 0 for transport failures
print(error.code) # e.g. TASK_NOT_FOUND
print(error.details) # server-provided diagnostics
print(error.request_id) # supplied by the server or proxy, when available
Every request accepts an options keyword containing headers and timeout. The client-wide timeout defaults to 30 seconds.
Session-only administration
Figranium's /api/settings/* endpoints require an authenticated session rather than an API key. Set session=True, log in through client.auth.login(...), and reuse the same client; httpx maintains its cookie jar automatically.
with Figranium(base_url="https://figranium.example", session=True) as admin:
admin.auth.login("admin@example.com", "password")
models = admin.settings.get_ai_models()
Custom HTTP clients
Supply an httpx.Client or httpx.AsyncClient to integrate custom transports, proxies, tracing, or test doubles. The SDK does not close a client supplied by the caller.
import httpx
http_client = httpx.Client(proxy="http://proxy.example:8080")
client = Figranium(api_key="...", http_client=http_client)
See docs/API.md for the full method index and examples for complete sync and async examples.
Compatibility
The initial Python release mirrors @figranium/sdk 0.2.0 and its Figranium API 0.14.4 compatibility target. Request payloads and responses remain dictionaries so newer servers can add fields without breaking SDK consumers.
License
Apache-2.0
Metadata
Release files for figranium-sdk 0.1.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 |
|---|---|---|---|---|
| figranium_sdk-0.1.0.tar.gz | 40.1 kB | Without provenance | Details for figranium_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| figranium_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for figranium_sdk-0.1.0-py3-none-any.whl |
Total release size: 63.3 kB
Release files / figranium_sdk-0.1.0.tar.gz
| Download URL | figranium_sdk-0.1.0.tar.gz |
|---|---|
| Size | 40.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
db82a7bbb6f934496e26c10b309cb3234c4f90855267a25281fd6ab48adca9d2
|
|
BLAKE2b-256 checksum How to use checksums |
84617ec4fd38ee427a412e4888b4cc17d57e29233be20c46f7643420f05f0935
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / figranium_sdk-0.1.0-py3-none-any.whl
| Download URL | figranium_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 23.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f9ca25fde0e65626a0220e3c79efca9b50a5e99eaf50394f2c50944d7a681fb1
|
|
BLAKE2b-256 checksum How to use checksums |
1e4ade5bfed38b1d72fd3b537de6b39346042315994d04b8b83dc4bb80d189d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for figranium-sdk 0.1.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.