roboto.http
Submodules
Package Contents
BEARER_TOKEN_HEADER
Bearer token which is parsed as a JWT to provide additional request context for invocations
BatchRequest
BatchResponse
Bases: pydantic.BaseModel, Generic[Model]
The response to a batch request, holding one element per request element, in the order the request sent them.
Every element of a batch is applied or refused on its own, so a batch can come back partly applied. succeeded and failed split the outcomes for a caller that does not care which request element produced which; read responses to trace an outcome back to the request element at its position.
Parameters
data AnyProperties
BatchResponse.failed
The exception the platform reported for each element it refused, in request order.
BatchResponse.map_data()
Convert what each applied element carries, leaving positions and failures untouched.
A batch call parses the platform’s answer into records and uses this to hand the caller domain objects instead: a SessionRecord becomes a Session. transform runs only on elements carrying data; a refused element keeps its exception, and every element keeps its position.
Parameters
transform collections.Builds the domain object an applied element’s record stands for.
Returns
A batch holding one element per element of this one, in the same order.
Attributes
BatchResponse.responses
BatchResponse.single()
The result carried by the only element of a one-element batch.
A singular call such as create_session() sends its one element through the plural counterpart and unwraps the answer with this, so its caller gets a raised exception rather than a batch to inspect.
Raises
Whatever the platform refused the element with.
The batch does not hold exactly one element, or holds one carrying neither a result nor an error.
Return type
BatchResponseElement
Bases: pydantic.BaseModel, Generic[Model]
One element of a response to a batch request, holding data when the operation succeeded and error when it failed, never both. An element holding neither reports an operation that returns no content, the batch equivalent of a 204 answer to a singular call.
Parameters
data AnyAttributes
BatchResponseElement.error
BatchResponseElement.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
BatchResponseElement.serialize_error()
Parameters
value Optional[roboto.info pydantic.Return type
BatchResponseElement.validate_error()
Build the exception an element was refused with, in whichever form the failure arrived.
Three forms reach this: an exception object, which is what an element copied from another batch carries; the envelope RobotoDomainException.to_dict() produces; and that envelope as JSON text, which is what RobotoDomainException declares to pydantic. Only a literal None yields None, which is how an element the platform applied or answered with no content arrives.
Any other value is a refusal, whatever shape it has. An envelope naming an exception class this release does not define, one missing its code or message, JSON that is not an envelope, and text that is not JSON all read as a RobotoUnrecognizedErrorException carrying whatever code and message could be recovered, with the value’s own text as the message when no message could be. That way a refused element is always in BatchResponse.failed, so a caller checking failed before treating a batch as done cannot mistake a garbled refusal for success.
plain mode replaces the validation the error annotation would otherwise apply. That annotation reads JSON text, so it would reject the exception object returned here.
Parameters
value AnyReturn type
BearerTokenDecorator
Decorates requests with a static, unchanging bearer token.
Parameters
token strCONNECTION_CONSISTENCY_HEADER
Header to control database read consistency for query/search endpoints.
Set to ‘strongly_consistent’ to force strongly consistent reads, or ‘eventually_consistent’ to force eventually consistent reads. Omission defaults to the API version’s default.
Only applies to query and search endpoints (e.g., /v1/query/*, /v1/datasets/query, /v1/files/query). Has no effect on other endpoints.
For API versions >= 2026-03-13, query endpoints default to eventually consistent reads. For older API versions, they default to strongly consistent reads for backward compatibility.
CONTENT_TYPE_JSON_HEADER
ClientError
DEFAULT_HTTP_TIMEOUT
HttpClient
Parameters
base_headers Optional[dict[str, str]]default_endpoint Optional[str]default_auth Optional[roboto.requester Optional[roboto.extra_headers_provider Optional[Callable[[], dict[str, str]]]default_timeout Optional[float]options Optional[roboto.Properties
HttpClient.auth_decorator
HttpClient.delete()
Parameters
url strdata Anyheaders Optional[dict]idempotent boolretry_wait Optional[roboto.timeout roboto.Return type
HttpClient.get()
Parameters
url strheaders Optional[dict]retry_wait Optional[roboto.idempotent booltimeout roboto.Return type
HttpClient.patch()
Parameters
url strdata Anyheaders Optional[dict]idempotent boolretry_wait Optional[roboto.timeout roboto.Return type
HttpClient.post()
Parameters
url strdata Anyheaders Optional[dict]idempotent boolretry_wait Optional[roboto.timeout roboto.Return type
HttpClient.put()
Parameters
url strdata Anyheaders Optional[dict]idempotent boolretry_wait Optional[roboto.timeout roboto.Return type
HttpClient.set_requester()
Parameters
requester roboto.HttpClient.url()
Parameters
path strReturn type
HttpClientOptions
Behavior of a HttpClient, applied to every request it makes.
Attributes
HttpClientOptions.logging
HttpClientOptions.retry
HttpError
HttpLoggingOptions
How a HttpClient renders requests into its logs.
Attributes
HttpLoggingOptions.scrub_headers
Header names, compared case-insensitively, whose values are replaced with * in every rendered form of a request the client produces. Authorization is always scrubbed, with or without an entry here.
HttpRequest
Parameters
url strmethod strheaders Optional[dict[str, str]]data Anyretry_wait Optional[roboto.idempotent boolHttpRequest.append_headers()
Parameters
headers dict[str, str]Return type
Properties
Attributes
HttpRequest.data
HttpRequest.describe()
Render the request for logging, with sensitive header values replaced by *.
Parameters
scrub_headers Collection[str]Header names, compared case-insensitively, to scrub in addition to ALWAYS_SCRUBBED_HEADERS.
Return type
Attributes
HttpRequest.headers
Properties
Attributes
HttpRequest.idempotent
HttpRequest.method
HttpRequest.retry_wait
HttpRequest.url
HttpRetryOptions
Whether and how many times a HttpClient retries a failed request.
Attributes
HttpRetryOptions.max_attempts
Total attempts per request, first try included. Values below 1 behave as 1: the first attempt always runs.
HttpRetryOptions.predicate
Called with the request and the exception a failed attempt raised; True means try again. None keeps the default, is_expected_to_be_transient(), which retries failures expected to be transient: DNS resolution failures unconditionally; connection errors, timeouts, and retryable HTTP statuses according to the request’s idempotency.
InvalidPaginationTokenError
Bases: ValueError
Raised when a pagination token cannot be parsed.
A pagination token is opaque to clients, so one that fails to decode or carries an unsupported scheme reflects bad caller input — a fabricated, truncated, or stale token — rather than a server fault. Subclasses ValueError so existing callers that catch ValueError around PaginationToken.from_token() keep working unchanged, while callers that want to distinguish this recoverable input error (e.g. to surface an actionable message instead of a generic 500 or runtime exception) can catch it specifically.
ORG_OVERRIDE_HEADER
Header to specify the organization that the user is acting on behalf of.
ORG_OVERRIDE_QUERY_PARAM
Query parameter to specify the organization that the user is acting on behalf of.
PaginatedList
Bases: pydantic.BaseModel, Generic[Model]
A list of records pulled from a paginated result set. It may be a subset of that result set, in which case next_token will be set and can be used to fetch the next page.
Parameters
data AnyAttributes
PaginatedList.next_token
Opaque token to fetch the next page of results.
If None, then this is the last page of results.
PaginationToken
A pagination token that can be treated as a truly opaque token by clients, with support for evolving the token format over time.
Parameters
Properties
PaginationToken.decode()
Base64 decode the data, adding back any trailing padding (“=”) as necessary to make data properly Base64.
Parameters
data strReturn type
PaginationToken.empty()
Return type
PaginationToken.encode()
Base64 encode the data and strip all trailing padding (“=”).
Parameters
data strReturn type
PaginationToken.from_token()
Parameters
token Optional[str]Return type
PaginationToken.json_token()
Parameters
data AnyReturn type
PaginationToken.to_token()
Return type
PaginationTokenEncoding
PaginationTokenScheme
RESOURCE_OWNER_OVERRIDE_HEADER
Header to specify the organization that owns the resource being accessed.
RESOURCE_OWNER_OVERRIDE_QUERY_PARAM
Query parameter to specify the organization that owns the resource being accessed.
ROBOTO_REQUESTER_HEADER
A JSON serialized RobotoRequester representing the entity making a request to Roboto.
RetryPredicate
Decides whether the exception warrants another attempt at the request.
RobotoClient
A client for making HTTP requests against Roboto service
Parameters
endpoint strauth_decorator Optional[roboto.http_client_kwargs Optional[dict[str, Any]]RobotoClient.defaulted()
Parameters
client Optional[RobotoClient]Return type
RobotoClient.delete()
Parameters
path ApiRelativePathcaller_org_id Optional[str]data Anyheaders Optional[dict[str, str]]idempotent boolowner_org_id Optional[str]query Optional[dict[str, Any]]retry_wait_fn Optional[roboto.timeout roboto.Return type
Properties
RobotoClient.for_profile()
Parameters
profile strReturn type
RobotoClient.from_config()
Parameters
config roboto.Return type
RobotoClient.from_env()
Return type
Properties
RobotoClient.get()
Parameters
path ApiRelativePathcaller_org_id Optional[str]headers Optional[dict[str, str]]idempotent boolowner_org_id Optional[str]query Optional[dict[str, Any]]retry_wait_fn Optional[roboto.timeout roboto.Return type
Properties
RobotoClient.http_client
RobotoClient.patch()
Parameters
path ApiRelativePathcaller_org_id Optional[str]data Anyheaders Optional[dict[str, str]]idempotent boolowner_org_id Optional[str]query Optional[dict[str, Any]]retry_wait_fn Optional[roboto.timeout roboto.Return type
RobotoClient.post()
Parameters
path ApiRelativePathcaller_org_id Optional[str]data Anyheaders Optional[dict[str, str]]idempotent boolowner_org_id Optional[str]query Optional[dict[str, Any]]retry_wait_fn Optional[roboto.timeout roboto.Return type
RobotoClient.put()
Parameters
path ApiRelativePathcaller_org_id Optional[str]data Anyheaders Optional[dict[str, str]]idempotent boolowner_org_id Optional[str]query Optional[dict[str, Any]]retry_wait_fn Optional[roboto.timeout roboto.Return type
RobotoRequester
Bases: pydantic.BaseModel
Details about the entity making a request to Roboto. These are embedded in a header in order to see what tool versions / operating systems are making requests, and to aid debugging.
Parameters
data AnyRobotoRequester.for_tool()
Called to intelligently populate a RobotoRequester for a request made from a named Roboto tool using the Python SDK.
Parameters
tool RobotoToolReturn type
Attributes
RobotoRequester.platform
The environment in which a request is being made, i.e. the user agent (for browser requests) or the results of platform.platform (for SDK requests)
RobotoRequester.roboto_tool
If a request is being made from a Roboto vended tool, the name of the tool
RobotoRequester.roboto_tool_details
If a request is being made from a Roboto vended tool, free text pertinent details about the tool
RobotoRequester.roboto_tool_version
If a request is being made from a Roboto vended tool, the version of the tool
RobotoRequester.schema_version
Roboto Requester payload schema version, used to ensure backward compatibility
RobotoTool
ServerError
SigV4AuthDecorator
Parameters
service strcredentials Optional[botocore.region Optional[str]SigV4AuthDecorator.lookup_credentials()
Return type
SigV4AuthDecorator.lookup_region()
Return type
StreamedList
Bases: pydantic.BaseModel, Generic[Model]
A StreamedList differs from a PaginatedList in that it represents a stream of data that is in process of being written to. Unlike a result set, which is finite and complete, a stream may be infinite, and it is unknown when or if it will complete.
Parameters
data AnyUSER_OVERRIDE_HEADER
Header to specify the user that is performing the REST operation.
USER_OVERRIDE_QUERY_PARAM
“Query parameter to specify the user that is performing the REST operation.
is_expected_to_be_transient()
The default retry predicate: whether exc is expected to be transient for request.
Parameters
request roboto.exc BaseExceptionReturn type
never_retry()
Retry predicate giving every request exactly one attempt.
Use for calls whose side effect must not run twice and where the server offers no idempotency key: a retried delivery (a chat message, an email) lands as a duplicate.
Parameters
_request roboto._exc BaseExceptionReturn type
roboto_headers()
Parameters
org_id Optional[str]user_id Optional[str]resource_owner_id Optional[str]additional_headers Optional[dict[str, str]]api_version roboto.