nebius.aio.request.Request

class documentation

class Request(Generic[Req, Res]): (source)

Constructor: Request(channel, service, method, request, ...)

Encapsulates an RPC invocation with retries and auth handling.

The Request object is the workhorse behind generated client methods. It manages the lifecycle of a single RPC including:

preparing and populating protobuf request objects,
attaching metadata and idempotency keys,
performing an authorization step when needed, and
executing retry logic with per-attempt timeouts.

Callers typically either await the request or call wait to run it synchronously.

Parameters, that are general for all types of requests and are passed through generated methods and various wrappers, are also encapsulated in the nebius.aio.request_kwargs.RequestKwargs class. Use this class to automatically infer and validate request parameters.

Example:

from nebius.sdk import SDK
from nebius.aio.cli_config import Config
from nebius.api.nebius.storage.v1 import (
    BucketServiceClient,
    CreateBucketRequest,
)

sdk = SDK(config_reader=Config())
service = BucketServiceClient(sdk)

# Create a request (typically done by generated client methods)
request = service.create(CreateBucketRequest(name="my-bucket"))

# Await the request asynchronously
response = await request
print(f"Created bucket: {response}")

# Or wait synchronously
response = request.wait()
print(f"Created bucket: {response}")

# Get request status
status = await request.status()
print(f"Request status: {status.code}")

# Get request ID
req_id = await request.request_id()
print(f"Request ID: {req_id}")

# Get trace ID
trace_id = await request.trace_id()
print(f"Trace ID: {trace_id}")

# Get initial metadata
initial_md = await request.initial_metadata()
print(f"Initial metadata: {dict(initial_md)}")

# Get trailing metadata
trailing_md = await request.trailing_metadata()
print(f"Trailing metadata: {dict(trailing_md)}")

# Synchronous helpers
req_id_sync = request.request_id_sync()
trace_id_sync = request.trace_id_sync()
initial_md_sync = request.initial_metadata_sync()
trailing_md_sync = request.trailing_metadata_sync()

Parameters
channel	Channel used to resolve address channels and perform synchronous execution when callers use the synchronous helpers.
service	Fully-qualified service name used to construct the RPC path (e.g. `"nebius.service.v1.MyService"`).
method	RPC method name (bare, without the service prefix), for example `"Get"` or `"List"`.
request	The request payload. Typically a protobuf wrapper or a domain object that can be serialised by the generated client.
result_pb2_class	Protobuf class used to deserialize the RPC response bytes into a message instance.
metadata	Optional initial gRPC metadata to attach to the call.
timeout	Overall timeout (seconds) applied to the request execution portion. Or `None` for infinite timeout. Default is `DEFAULT_TIMEOUT`.
auth_timeout	Timeout budget (seconds) reserved for authorization flows plus the request execution. When provided the total authorization + request time will not exceed this value. Default is `DEFAULT_AUTH_TIMEOUT`. Provide `None` for infinite timeout.
auth_options	Optional dictionary forwarded to the authenticator when performing authorization. See the authenticator documentation for provider-specific keys.
credentials	Optional gRPC `CallCredentials` to use for the RPC invocation.
compression	Optional gRPC compression setting for the RPC.
result_wrapper	Optional callable used to post-process the raw protobuf response into a higher-level domain object. It is called as `result_wrapper(service_method: str, channel: Channel, pb_obj)`.
grpc_channel_override	Optionally provide an `AddressChannel` instance to use instead of resolving one from the main channel. This is useful for tests or when the caller already has a concrete address-bound channel.
error_wrapper	Optional callable that maps a `RequestStatus` into a `RequestError` subclass used by the SDK. When omitted a default service-specific wrapper is used.
retries	Number of retry attempts for transient failures. Default is 3.
per_retry_timeout	Timeout (seconds) applied to each retry attempt individually. You can pass `None` for infinite timeout. Default is `DEFAULT_PER_RETRY_TIMEOUT`.

Method	`__await__`	Support awaiting the Request instance.
Method	`__init__`	Initialize the request with the provided parameters.
Method	`__repr__`	Return a short representation including service, method and status.
Method	`cancel`	Cancel the request; returns True when the request is marked cancelled.
Method	`cancelled`	Return True if the call was cancelled (locally or remotely).
Method	`compression.setter`	Undocumented
Method	`credentials.setter`	Undocumented
Method	`current_status`	Return the current request status or an unfinished sentinel.
Method	`done`	Return True if the underlying gRPC call has completed.
Async Method	`initial_metadata`	Return the initial metadata from the RPC, awaiting the request if necessary.
Method	`initial_metadata_sync`	Synchronously return the initial metadata received from the RPC.
Method	`input_metadata`	Return the metadata that will be sent with the request (mutable).
Async Method	`request_id`	Return the request id extracted from initial metadata. This coroutine will await the request if metadata hasn't yet been received.
Method	`request_id_sync`	Synchronous helper to return the request id.
Method	`run_sync_with_timeout`	Run an awaitable synchronously using the channel's sync runner.
Async Method	`status`	Return the final request status, awaiting completion if needed.
Method	`timeout.setter`	Undocumented
Async Method	`trace_id`	Return the trace id extracted from initial metadata. This coroutine will await the request if metadata hasn't yet been received.
Method	`trace_id_sync`	Synchronous helper to return the trace id.
Async Method	`trailing_metadata`	Return the trailing metadata from the RPC, awaiting the request if necessary.
Method	`trailing_metadata_sync`	Synchronously return the trailing metadata received from the RPC.
Method	`wait`	Synchronous convenience wrapper for awaiting the request.
Method	`wait_for_ready.setter`	Undocumented
Property	`compression`	Return the configured compression option for the RPC call.
Property	`credentials`	Return optional gRPC CallCredentials attached to the request.
Property	`timeout`	Return the configured overall timeout for the request in seconds.
Property	`wait_for_ready`	Return the wait_for_ready flag used when starting the RPC call.
Async Method	`_await_result`	Ensure the request coroutine is scheduled and return its result.
Method	`_convert_request_error`	Attempt to raise a RequestError from an AioRpcError, swallowing any resulting RequestError.
Async Method	`_get_request_id`	Ensure metadata is received and return the request and trace ids.
Method	`_parse_request_id`	Extract request and trace ids from cached initial metadata.
Method	`_raise_request_error`	Convert a gRPC AioRpcError into the SDK's RequestError and status.
Async Method	`_request_with_authorization_loop`	Wrap request retry loop with an authorization loop.
Async Method	`_retry_loop`	Core retry loop for the RPC invocation.
Method	`_send`	Prepare and start the underlying gRPC unary-unary call.
Instance Variable	`_auth_options`	Undocumented
Instance Variable	`_auth_timeout`	Undocumented
Instance Variable	`_awaited`	Undocumented
Instance Variable	`_call`	Undocumented
Instance Variable	`_cancelled`	Undocumented
Instance Variable	`_channel`	Undocumented
Instance Variable	`_compression`	Undocumented
Instance Variable	`_credentials`	Undocumented
Instance Variable	`_error_wrapper`	Undocumented
Instance Variable	`_future`	Undocumented
Instance Variable	`_grpc_channel`	Undocumented
Instance Variable	`_initial_metadata`	Undocumented
Instance Variable	`_input`	Undocumented
Instance Variable	`_input_metadata`	Undocumented
Instance Variable	`_method`	Undocumented
Instance Variable	`_per_retry_timeout`	Undocumented
Instance Variable	`_request_id`	Undocumented
Instance Variable	`_result_pb2_class`	Undocumented
Instance Variable	`_result_wrapper`	Undocumented
Instance Variable	`_retries`	Undocumented
Instance Variable	`_sent`	Undocumented
Instance Variable	`_service`	Undocumented
Instance Variable	`_start_time`	Undocumented
Instance Variable	`_status`	Undocumented
Instance Variable	`_timeout`	Undocumented
Instance Variable	`_trace_id`	Undocumented
Instance Variable	`_trailing_metadata`	Undocumented
Instance Variable	`_wait_for_ready`	Undocumented

def __await__(self) -> Generator[Any, None, Res]: (source) ¶

Support awaiting the Request instance.

The first await schedules the internal request; awaiting a finished request raises a RuntimeError to prevent double-execution semantics.

def __init__(self, channel: Channel, service: str, method: str, request: Req, result_pb2_class: type[PMessage], metadata: Metadata | Iterable[tuple[str, str]] | None = None, timeout: float | None | UnsetType = Unset, auth_timeout: float | None | UnsetType = Unset, auth_options: dict[str, str] | None = None, credentials: CallCredentials | None = None, compression: Compression | None = None, result_wrapper: Callable[[str, Channel, Any], Res] | None = None, grpc_channel_override: AddressChannel | None = None, error_wrapper: Callable[[RequestStatus], RequestError] | None = None, retries: int | None = 3, per_retry_timeout: float | None | UnsetType = Unset): (source) ¶

Initialize the request with the provided parameters.

def __repr__(self) -> str: (source) ¶

Return a short representation including service, method and status.

def cancel(self) -> bool: (source) ¶

Cancel the request; returns True when the request is marked cancelled.

If the underlying gRPC call has already been created, cancellation is propagated to that call; otherwise a local cancelled flag is set so the call will not be sent when the request is executed.

def cancelled(self) -> bool: (source) ¶

Return True if the call was cancelled (locally or remotely).

@compression.setter
def compression(self, compression: Compression | None): (source) ¶

Undocumented

@credentials.setter
def credentials(self, credentials: CallCredentials | None): (source) ¶

Undocumented

def current_status(self) -> RequestStatus | UnfinishedRequestStatus: (source) ¶

Return the current request status or an unfinished sentinel.

When the RPC has not yet started this returns UnfinishedRequestStatus.INITIALIZED. When the call is in progress it returns UnfinishedRequestStatus.SENT. When the call completed it returns a concrete RequestStatus.

Returns
either `nebius.aio.request_status.RequestStatus` or `nebius.aio.request_status.UnfinishedRequestStatus`	Undocumented

def done(self) -> bool: (source) ¶

Return True if the underlying gRPC call has completed.

async def initial_metadata(self) -> Metadata: (source) ¶

Return the initial metadata from the RPC, awaiting the request if necessary.

If the request failed but initial metadata was still produced it will be returned. Otherwise a RequestError is raised.

def initial_metadata_sync(self) -> Metadata: (source) ¶

Synchronously return the initial metadata received from the RPC.

If initial metadata is not already cached this helper awaits the request (via the sync runner) and returns the initial metadata. :returns: initial metadata :rtype: nebius.base.metadata.Metadata

def input_metadata(self) -> Metadata: (source) ¶

Return the metadata that will be sent with the request (mutable).

This object may be modified by authenticators before the request is sent.

async def request_id(self) -> str: (source) ¶

Return the request id extracted from initial metadata. This coroutine will await the request if metadata hasn't yet been received.

This is a convenience wrapper over _get_request_id.

def request_id_sync(self) -> str: (source) ¶

Synchronous helper to return the request id.

If the id is already cached it is returned synchronously. Otherwise the request is awaited via the sync runner and the id is returned.

def run_sync_with_timeout(self, func: Awaitable[T]) -> T: (source) ¶

Run an awaitable synchronously using the channel's sync runner.

The channel's synchronous runner is invoked with the request's authorization timeout budget (_auth_timeout). In case the sync runner raises a TimeoutError this method converts it into a RequestError populated with a DEADLINE_EXCEEDED status so callers can inspect the failure uniformly.

Parameters
func:`Awaitable[T]`	awaitable to execute
Returns
`T`	result of the awaitable
Raises
`RequestError`	when execution times out or the request fails

async def status(self) -> RequestStatus: (source) ¶

Return the final request status, awaiting completion if needed.

When the request fails but a status object is still available it is returned. Otherwise a RequestError is raised.

@timeout.setter
def timeout(self, timeout: float | None): (source) ¶

Undocumented

async def trace_id(self) -> str: (source) ¶

Return the trace id extracted from initial metadata. This coroutine will await the request if metadata hasn't yet been received.

This is a convenience wrapper over _get_request_id.

def trace_id_sync(self) -> str: (source) ¶

Synchronous helper to return the trace id.

If the id is already cached it is returned synchronously. Otherwise the request is awaited via the sync runner and the id is returned.

async def trailing_metadata(self) -> Metadata: (source) ¶

Return the trailing metadata from the RPC, awaiting the request if necessary.

If the request failed but trailing metadata was still produced it will be returned. Otherwise a RequestError is raised.

def trailing_metadata_sync(self) -> Metadata: (source) ¶

Synchronously return the trailing metadata received from the RPC.

If trailing metadata is not already cached this helper awaits the request (via the sync runner) and returns the trailing metadata. :returns: trailing metadata :rtype: nebius.base.metadata.Metadata

def wait(self) -> Res: (source) ¶

Synchronous convenience wrapper for awaiting the request.

Equivalent to run_sync_with_timeout(self).

@wait_for_ready.setter
def wait_for_ready(self, wait_for_ready: bool | None): (source) ¶

Undocumented

@property
compression: Compression | None = (source) ¶

Return the configured compression option for the RPC call.

@property
credentials: CallCredentials | None = (source) ¶

Return optional gRPC CallCredentials attached to the request.

@property
timeout: float | None = (source) ¶

Return the configured overall timeout for the request in seconds.

None means no timeout.

@property
wait_for_ready: bool | None = (source) ¶

Return the wait_for_ready flag used when starting the RPC call.

async def _await_result(self) -> Res: (source) ¶

Ensure the request coroutine is scheduled and return its result.

This helper memoizes the created Future so the underlying request is executed only once even if multiple awaiters call it.

def _convert_request_error(self, err: AioRpcError): (source) ¶

Attempt to raise a RequestError from an AioRpcError, swallowing any resulting RequestError.

This helper is used to set status and other metadata that came with the AioRpcError without actually raising the RequestError.

async def _get_request_id(self) -> tuple[str, str]: (source) ¶

Ensure metadata is received and return the request and trace ids.

Returns a tuple (request_id, trace_id) extracted from the initial metadata. This coroutine will await the request if metadata hasn't yet been received.

def _parse_request_id(self): (source) ¶

Extract request and trace ids from cached initial metadata.

Raises RequestError when initial metadata is not present.

def _raise_request_error(self, err: AioRpcError): (source) ¶

Convert a gRPC AioRpcError into the SDK's RequestError and status.

This extracts initial/trailing metadata, parses request identifiers and attempts to convert the gRPC status into the SDK's structured RequestStatus. The resulting status is stored on self._status and a nebius.aio.service_error.RequestError is raised.

async def _request_with_authorization_loop(self) -> Res: (source) ¶

Wrap request retry loop with an authorization loop.

The authorization loop will attempt to authenticate and then execute the request retry loop. If the result is UNAUTHENTICATED and the authenticator allows retry, it will re-authenticate and try again while respecting the overall auth timeout.

async def _retry_loop(self, outer_deadline: float | None = None) -> Res: (source) ¶

Core retry loop for the RPC invocation.

This coroutine executes the RPC, applies per-attempt and overall timeouts, and implements retry/backoff rules for retriable errors. It returns the RPC result or raises the error that terminated the operation.

Parameters
outer_deadline:`float \| None`	optional absolute timestamp (time.time()) that caps the total time budget for this retry loop.
Returns
`Res`	the deserialized RPC result (or wrapped result via `result_wrapper` when configured).
Raises
`RequestError, AioRpcError, CancelledError`	depending on the failure mode.

def _send(self, timeout: float | None): (source) ¶

Prepare and start the underlying gRPC unary-unary call.

Responsibilities:

Validate/serialize the request payload.
Populate parent identifiers into the request when absent and the channel exposes a parent id.
Resolve an AddressChannel via Channel.get_channel_by_method when no override was provided.
Create the gRPC call object and store it on self._call.

Parameters
timeout:optional `float`	per-attempt timeout to use for the RPC invocation.
Raises
`RequestError`	when the request payload cannot be serialized or the request has been cancelled.