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 whose timeout comfortably exceeds workflow duration.

from makra import Makra

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

The connection stays open until a terminal result arrives. 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.