Choose an execution style

The SDK exposes the same extraction and schema workflows in three execution styles. Choose based on connection lifetime and recovery needs, not on extraction semantics.

Blocking

Use extract() or schema() for scripts, command-line jobs, and request handlers that want one call and one final result.

from makra import Makra

with Makra() as client:
    response = client.extract(
        ["https://news.example/articles/memoization"],
        {"headline": "The article headline"},
    )

Version 0.0.4 submits the workflow durably, polls it to a terminal state, and downloads the stored result. The default workflow timeout is 300 seconds per page budget. Sequential multi-URL calls and configured pagination increase the computed deadline when you do not pass an explicit timeout.

Streaming

Use extract_stream() or schema_stream() when a user needs visible progress or your service wants live diagnostics. The stream carries events, not the final result payload. Read event.run_id, wait for a terminal event, then call get_run_result().

Streaming can reconnect after a dropped connection when the server has assigned a run ID. The SDK resumes from the last event sequence within its retry budget.

Deferred

Use submit_extract() or submit_schema() for queues, webhooks, background workers, and any process that may restart before the workflow finishes. Submission returns a handle immediately. The run and its stored result live on the service.

from makra import Makra

with Makra() as client:
    run = client.submit_extract(
        ["https://shop.example/products/atlas-lamp"],
        {"price": "The current selling price"},
    )
    print(run.id)

Persist the run ID before doing more work. A different process can later call get_run(), stream_run_events(), wait_for_run(), or get_run_result().

Synchronous and asynchronous clients

AsyncMakra mirrors Makra. Ordinary methods are awaitable. Stream methods return async iterators.

import asyncio

from makra import AsyncMakra


async def main() -> None:
    async with AsyncMakra() as client:
        response = await client.extract(
            ["https://news.example/articles/memoization"],
            {"headline": "The article headline"},
        )
        print(response)


asyncio.run(main())

Use the async client in an async application. Do not call the synchronous client directly from an event loop thread.

Next, stream progress or manage deferred runs.