Python SDK: getting started

Python scenarios use the same Akmelo pipeline as PHP and JavaScript: published versions, manual and trial runs, schedules, logs, record quality, and exports. Choose Python when creating a scenario. The language belongs to the scenario: pasting Python into a PHP version does not change its runtime.

First scenario

The entry point is a regular synchronous def run(ctx): function. Akmelo creates ctx for each run. SDK methods are synchronous. Do not add async or await; you do not need requests, pandas, a separate HTTP client, or package installation.

def run(ctx):
    url = ctx.param('catalog_url', '')
    if not url:
        ctx.abort('Enter a catalog URL')
    response = ctx.http().get(url)
    if not response.ok():
        ctx.fail('Catalog returned HTTP ' + str(response.status))
    for card in response.dom().qa('.product-card'):
        sku = card.attr('data-sku')
        if not sku:
            continue
        name = card.q('.title')
        price = card.q('.price')
        ctx.emit({
            'sku': sku,
            'name': name.text() if name is not None else '',
            'price': ctx.text().money(price.text() if price is not None else None),
        }, sku)

The selectors .product-card, .title, .price, and data-sku are examples. Choose and test selectors for your source. A return value from run does not become records: call ctx.emit(record, key). A stable key updates the same product in the next run; do not generate a new random key each time.

Reading this reference

Python method names and properties use snake_case: with_headers, put_from_url, wait_for, final_url. Service data uses dictionaries and lists: item['sku'], result.get('records', []), regions[0]['id']. SDK objects have methods such as response.json() and document.sheet(0). Python uses None, True, and False; Akmelo serializes those values to JSON.

Recommended workflow

1. Create a Python scenario for a site and supply its source parameters.
2. Save and validate the code. Validation does not request the website or prove selectors work.
3. Run a small trial. Check keys, types, prices, missing values, and the request log.
4. Publish the tested version and run it manually. Then configure a schedule and its time zone.
5. Open the records and configure the export mapping. CSV, JSON, XML, HTTP endpoints, files, Webhooks, and supported databases share the same record pipeline regardless of collection language.

Complete examples: pagination, JSON, first algorithm.

Isolation and data types

The runtime uses CPython 3.13 in a separate restricted process. It executes validated scenario code with an SDK, rather than granting general access to a server. Network, browser, files, mail, documents, credentials, and AI go through ctx and the current site's policies. Direct sockets, file access, child processes, shell commands, dynamic code execution, unsafe introspection, and arbitrary imports are blocked. A scenario cannot run pip install. See environment.

Pass a dictionary containing JSON-compatible values to emit: strings, finite numbers, booleans, None, lists, and dictionaries. Convert sets, bytes, Decimal, datetime, generators, DOM nodes, and documents explicitly before emitting them. Never log secrets or personal content.

Self-hosted agents

The selected agent must enable Python and run a release containing this runtime. A PHP-only agent cannot execute Python. Browser support is a separate capability. The agent executes previously received signed definitions and can retain local records and exports; cloud record availability depends on mirroring. AI and other cloud services require connectivity. A Python export transformation also needs Python on the machine executing that export.

Python step debugging with breakpoints is unavailable. Use validation, trials, logs, metrics, and small input samples.

Working with CAPTCHA: complete examples

Explore catalogs, pagination, batch loading, scrolling, sign-in, JavaScript rendering and control pages in the dedicated section. Each of the 12 walkthroughs includes settings, complete source and an explanation of the algorithm.

Explicit CAPTCHA tasks

Current type catalog, input schemas, cost quotations and task results are available through ctx.captcha(). The API works in the cloud and on agents with workspace billing. Reference.