Python SDK: Context: inputs, output, and progress
The platform passes ctx into def run(ctx):. Use it to read inputs, call allowed services, and return records. Do not construct ctx yourself.
Examples are fragments inside def run(ctx):. All SDK methods are synchronous; do not add await.
Methods
http()state()storage()browser()captcha()wildberries()dom()json()text()url()emit()flush()log()progress()metric()param()params()credential()sleep()cancelled()abort()fail()now()mail()documents()ai()sources()
http
ctx.http() -> HttpClient
No arguments.
Result: HttpClient. An SDK object; use its methods instead of emitting it directly.
Get a client for requests to the site. All requests use the current site's network settings.
result = ctx.http()
state
ctx.state() -> KeyValue
No arguments.
Result: KeyValue. An SDK object; use its methods instead of emitting it directly.
Get a small store for traversal state, such as the last processed page number.
result = ctx.state()
storage
ctx.storage(code) -> Storage
| Argument | Type | Required | Purpose |
|---|---|---|---|
code |
str |
Yes | Code of a configured connection. |
Result: Storage. An SDK object; use its methods instead of emitting it directly.
Select an S3 file store by connection code. Configure the connection and allow it for the site first.
result = ctx.storage('media')
browser
ctx.browser() -> Browser
No arguments.
Result: Browser. An SDK object; use its methods instead of emitting it directly.
Get a browser for pages that need Python, clicks, or scrolling.
result = ctx.browser()
wildberries
ctx.wildberries() -> Wildberries
No arguments.
Result: Wildberries. An SDK object; use its methods instead of emitting it directly.
Get the ready-made product source for a site created with the Wildberries solution. Products and regions come from site settings. See all methods and an example.
result = ctx.wildberries()
dom
ctx.dom(html, base_url=None) -> Dom
| Argument | Type | Required | Purpose |
|---|---|---|---|
html |
str |
Yes | HTML string, not a file path or download URL. |
base_url |
str | None |
No, see the signature default | Base URL for relative links. |
Result: Dom. An SDK object; use its methods instead of emitting it directly.
Parse HTML already obtained. base_url lets relative links become absolute.
result = ctx.dom('<a href="/product">Product</a>', 'https://example.com')
json
ctx.json(text) -> Any
| Argument | Type | Required | Purpose |
|---|---|---|---|
text |
str |
Yes | Text to parse, search, or type. |
Result: Any.
Parses JSON text using Python. Invalid JSON throws; the Python method has no depth parameter.
result = ctx.json('{"items": []}')
text
ctx.text() -> TextTools
No arguments.
Result: TextTools. An SDK object; use its methods instead of emitting it directly.
Get tools for cleaning text, prices, and product codes.
result = ctx.text()
url
ctx.url() -> UrlTools
No arguments.
Result: UrlTools. An SDK object; use its methods instead of emitting it directly.
Get tools for links, query parameters, and page URL templates.
result = ctx.url()
emit
ctx.emit(item, key=None) -> None
| Argument | Type | Required | Purpose |
|---|---|---|---|
item |
dict[str, Any] |
Yes | Record dictionary with string keys and JSON-compatible values. |
key |
str | None |
No, see the signature default | Record, state, object, or workflow-input key, depending on the method. |
Result: None. The method does not return a data value.
Adds a plain Python dict to the output. Do not emit Response, Dom, or Document instances wholesale: select the fields you need. A stable key lets a later run update the record.
ctx.emit({'sku': 'A-1', 'price': 1250}, 'A-1')
flush
ctx.flush() -> None
No arguments.
Result: None. The method does not return a data value.
Send accumulated records without waiting for the automatic flush.
result = ctx.flush()
log
ctx.log(message, context=None, level='info') -> None
| Argument | Type | Required | Purpose |
|---|---|---|---|
message |
str |
Yes | Message without secrets or private content. |
context |
dict[str, Any] | None |
No, see the signature default | Extra JSON-compatible log context without secrets. |
level |
str |
No, see the signature default | Run-log severity. |
Result: None. The method does not return a data value.
Write a clear message to the run log. Pass extra values in context.
ctx.log('Collection started', {'category': 'cables'}, 'info')
progress
ctx.progress(done, total=None, label=None, percent=None) -> None
| Argument | Type | Required | Purpose |
|---|---|---|---|
done |
int |
Yes | Completed work count. |
total |
int | None |
No, see the signature default | Total work, or None when unknown. |
label |
str | None |
No, see the signature default | Human-readable stage name. |
percent |
float | None |
No, see the signature default | Optional known completion percentage. |
Result: None. The method does not return a data value.
Report work completed and a user-facing stage name. You may not know total in advance.
ctx.progress(1, 10, 'Catalog')
metric
ctx.metric(name, value=1) -> None
| Argument | Type | Required | Purpose |
|---|---|---|---|
name |
str |
Yes | Field, header, file, credential, or metric name, depending on the method. |
value |
Any |
No, see the signature default | Method-specific value; see its result description. |
Result: None. The method does not return a data value.
Add a numeric execution metric, such as the number of skipped products.
ctx.metric('processed', 1)
param
ctx.param(name, default=None) -> Any
| Argument | Type | Required | Purpose |
|---|---|---|---|
name |
str |
Yes | Field, header, file, credential, or metric name, depending on the method. |
default |
Any |
No, see the signature default | Fallback when no value is available. |
Result: Any.
Get one run parameter. default is used if the parameter is absent or None.
result = ctx.param('catalog_url', '')
params
ctx.params() -> dict[str, Any]
No arguments.
Result: dict[str, Any].
Get all run parameters.
result = ctx.params()
credential
ctx.credential(name) -> str
| Argument | Type | Required | Purpose |
|---|---|---|---|
name |
str |
Yes | Field, header, file, credential, or metric name, depending on the method. |
Result: str.
Get a named secret for the target website. Its name must match a configured key.
result = ctx.credential('site_token')
sleep
ctx.sleep(ms) -> None
| Argument | Type | Required | Purpose |
|---|---|---|---|
ms |
int |
Yes | Pause in milliseconds; platform clamps it to 0–60000. |
Result: None. The method does not return a data value.
Make a controlled pause. The argument is in milliseconds.
ctx.sleep(250)
cancelled
ctx.cancelled() -> bool
No arguments.
Result: bool.
Check whether the user requested a stop. Do this in long loops.
result = ctx.cancelled()
abort
ctx.abort(reason) -> NoReturn
| Argument | Type | Required | Purpose |
|---|---|---|---|
reason |
str |
Yes | Safe, human-readable stop/failure explanation. |
Result: NoReturn.
Stop execution with an explanation and retain state for a possible resume. The run receives a stopped status. Use fail() if the source returns an error or data is malformed.
ctx.abort('Collection stopped')
fail
ctx.fail(reason) -> NoReturn
| Argument | Type | Required | Purpose |
|---|---|---|---|
reason |
str |
Yes | Safe, human-readable stop/failure explanation. |
Result: NoReturn.
End a run with an error when the source is unavailable or its response differs from the expected format. Unlike abort(), this stop is recorded as a failure rather than a cancellation.
ctx.fail('Website returned an unexpected response')
now
ctx.now() -> datetime
No arguments.
Result: datetime.
Returns a timezone-aware datetime.datetime in UTC. Use ctx.now().isoformat() for JSON; a datetime object itself cannot be emitted.
result = ctx.now()
ctx.mail() -> Mail
No arguments.
Result: Mail. An SDK object; use its methods instead of emitting it directly.
Opens inbound-mail methods inside a mail scenario. Content is available only for the pinned event.
result = ctx.mail()
documents
ctx.documents() -> Documents
No arguments.
Result: Documents. An SDK object; use its methods instead of emitting it directly.
Opens parsing of allowed Excel, PDF, Word, CSV, and text files.
result = ctx.documents()
ai
ctx.ai() -> Ai
No arguments.
Result: Ai. An SDK object; use its methods instead of emitting it directly.
Opens data analysis, extraction, and transformation methods. AI calls are synchronous and count against the workspace budget.
result = ctx.ai()
sources
ctx.sources() -> Sources
No arguments.
Result: Sources. An SDK object; use its methods instead of emitting it directly.
Opens pinned workflow inputs and local price comparison. Inputs are available only to the corresponding workflow scenario.
result = ctx.sources()
yandex_market
ctx.yandex_market() -> YandexMarket
No arguments.
Result: YandexMarket. An SDK object; use its methods instead of emitting it directly.
Return the configured Yandex Market source. Its methods retain the source policy checks.
result = ctx.yandex_market()
Errors and execution context
All calls are synchronous. Invalid arguments or malformed source data can raise ValueError/TypeError; a platform refusal or unavailable service raises RuntimeError. Missing elements/values return None or an empty collection only where explicitly documented. Do not convert every exception into an empty successful result. External-service methods are unavailable in export transformations; see transformation limits and environment.
captcha
captcha() -> Captcha
Returns the explicit task API. Catalog and quotation methods do not submit a paid task. Creation, status retrieval and feedback work through the workspace account in the cloud and on an agent.