Skip to content

Types

The public model vocabulary: results, statuses, task addressing, proxy, secret strings, Money, and the three config types. All are frozen dataclasses re-exported from the package root.

Public model vocabulary (ADR-0036): result/status types, task addressing, proxy, secret strings, and the three config types.

All models are frozen dataclasses re-exported from the package root.

Money dataclass

An amount in a named currency (currency-aware costs, ADR-0040).

currency is an ISO-4217-style code. The currency is declared per service/adapter (never parsed from the provider wire, which returns bare numbers); defaults are USD, with RUB for the RuCaptcha mirror (api.rucaptcha.com). Plain value type: no arithmetic operators, so amounts in different currencies cannot be mixed accidentally.

TaskStatus

Bases: Enum

Provider-side task outcomes, as answered by status queries.

TaskRef dataclass

Public, constructible identity of a task: (provider, task_id).

Survives process restarts (persist the pair); routing vehicle for all task-addressing operations (ADR-0045).

task_id is int | str: most providers use integer ids, but Capsolver addresses tasks by UUID string (task-14 verification).

TaskResult dataclass

Bases: Generic[T]

Rich result of a solved task (ADR-0008, ADR-0034).

solution is non-optional: this type is produced only by solve() and wait(), which never return pending states.

task_ref property 

task_ref

TaskRef for aux-op addressing (ADR-0045).

TaskStatusResult dataclass

Answer of a single-shot status query (ADR-0032, ADR-0056).

Non-generic and carries no submission metadata: solution is BaseSolution | None, populated only when status is READY.

TaskTicket dataclass

Bases: Generic[T]

Ticket issued by submit() (ADR-0067, ADR-0075).

Not user-constructible: its value is provenance — the bound solution type T and submitted_at are only meaningful for a task the engine really submitted. Obtain one from Solver.submit() / AsyncSolver.submit(). instant_answer is set iff the provider answered the submit itself (instant tasks); wait() fast-paths on it. time is the resolved solve-timeline config carried from submit (ADR-0030); wait() derives its default budget and poll cadence from it.

ParsedTask dataclass

Public adapter-SDK vocabulary: parsed getTaskResult response (ADR-0058, formalized by ADR-0075).

SubmitAccepted dataclass

Public adapter-SDK vocabulary: parsed createTask response (ADR-0075). task_id is always present (int | str — Capsolver uses UUID strings); instant_answer is set iff the provider answered inline.

ProxyKind

Bases: Enum

Proxy scheme; values are sent verbatim (ADR-0012, ADR-0028).

Proxy dataclass

Structured proxy configuration (ADR-0012).

host must be non-empty and port in 1..65535; violations raise InvalidConfigError at construction. password stays a plain str (masking contracts are scoped to API keys, ADR-0014).

SecretStr

Secret value wrapper with a full-mask repr/str (ADR-0014).

  • repr/str render *** (no partial characters).
  • Value equality against another SecretStr; comparing to anything else is a category error and raises TypeError (None compares False).
  • hash is the hash of the wrapped value.
  • Picklable.

NetworkConfig dataclass

Network-level knobs (ADR-0024): per-request timeout and connection pool limits. None means "unspecified" (ADR-0043); explicit values are validated at construction (ADR-0042).

TimeConfig dataclass

Solve-timeline config (ADR-0043, ADR-0030): the outer wall-clock budget (total_timeout) and the poll cadence (poll_interval, poll_delay). None means "unspecified".

RetryConfig dataclass

Retry strategy (ADR-0043, ADR-0042): attempt count and backoff shape. backoff_cap must be >= backoff_base (a cap below its own base cannot back off).