nebius.sdk.SDK

class documentation

class SDK(Channel): (source)

Constructor: SDK(resolver, substitutions, user_agent_prefix, domain, ...)

View In Hierarchy

High-level SDK facade providing convenience helpers for Nebius services.

The SDK class is a thin convenience wrapper around a gRPC channel that exposes higher-level helpers for common operations such as retrieving the current authenticated profile. It inherits from Channel and therefore also exposes the channel-level behaviors and helpers (resolution, pooling, credential wiring, sync/async helpers).

Quick start -- initialization

Common ways to construct the SDK:

  • From an IAM token in the environment (default behavior):

    sdk = SDK()

  • With an explicit token string or static bearer:

    sdk = SDK(credentials="MY_IAM_TOKEN")
# or
sdk = SDK(credentials=Bearer("MY_IAM_TOKEN"))

  • From an env-backed token provider:

    from nebius.aio.token.static import EnvBearer
sdk = SDK(credentials=EnvBearer("NEBIUS_IAM_TOKEN"))

  • From the CLI config reader (reads endpoints/profile like the CLI):

    from nebius.aio.cli_config import Config
sdk = SDK(config_reader=Config())

  • Service account private key or credentials file:

    sdk = SDK(service_account_private_key_file_name="private.pem",
        service_account_public_key_id="pub-id",
        service_account_id="service-account-id")
# or
sdk = SDK(credentials_file_name="path/to/credentials.json")

Async vs sync usage and lifecycle

The SDK is designed for asyncio. Prefer the async context manager which ensures graceful shutdown of background tasks:

async with SDK(...) as sdk:
    resp = await sdk.whoami()

Synchronous usage is supported but riskier. It may raise nebius.aio.channel.LoopError if used inside an active loop. For sync use:

sdk = SDK(...)
try:
    resp = sdk.whoami().wait()
finally:
    sdk.sync_close()

If you provide a separate event loop at construction you can safely call synchronous helpers from threads; otherwise avoid mixing sync calls with a running event loop.

Authentication and auth_timeout

  • Many calls accept an auth_timeout parameter which bounds the total time spent acquiring or renewing credentials plus the enclosed request.
  • Default: 15 minutes (900 seconds). Pass auth_timeout=None to disable the bound (be cautious -- this can hang indefinitely if auth cannot complete).
  • auth_options may be provided to control renewal behavior (for example to make token renewal synchronous or to surface renewal errors as request errors).

Timeouts and retries (summary)

  • The SDK uses two timeout levels:
    • overall request timeout (deadline for entire request including retries),
    • per-retry timeout (deadline for each individual retry attempt).
  • Defaults used by the SDK (unless overridden by a call):
    • overall request timeout: 60s
    • per-retry timeout: 20s (derived from 60s / 3 retries)
  • Set timeout=None to disable the request deadline.
  • Configure retries and per_retry_timeout per-call when needed.

Parent ID auto-population

  • Some methods (list, get_by_name, get, many others) may have a parent_id automatically populated from CLI nebius.aio.cli_config.Config or the SDK parent_id provided at initialization.
  • To disable automatic parent population while retaining CLI config use the Config option no_parent_id=True.

Operations

  • Long-running operations returned by service create/update or other calls are represented by an nebius.aio.operation.Operation wrapper that can be awaited until completion. You can also list operations via the source service's operation_service() helper.
  • The Operation wrapper provides convenience helpers like .wait() and .resource_id.

Request metadata and debugging

  • Service methods return Request objects. These provide access to additional metadata (request id, trace id) and can be awaited or waited on synchronously.

  • Example:

    request = sdk.whoami()   # does not await immediately
resp = await request
request_id = await request.request_id()
trace_id = await request.trace_id()

Error handling and nebius.aio.service_error.RequestError

User-agent customization

  • Add custom user-agent parts via options (grpc.primary_user_agent) or the user_agent_prefix parameter when constructing the SDK. The SDK composes the final user-agent from these pieces and the internal SDK version string.

See also

  • Full usage examples and deeper explanations are available in the project README and the API reference documentation.
Method whoami Return a request that fetches the profile for the current credentials.

Inherited from Channel:

Async Method __aenter__ Enter the async context manager. Returns self to allow usage like:
Async Method __aexit__ Exit the async context manager. Calls close() to gracefully shut down resources.
Method __init__ Construct a new Channel instance.
Method bg_task Run a coroutine in the background and log uncaught exceptions.
Async Method channel_ready Channel is always ready, nothing to do here.
Async Method close Gracefully close the channel and all associated background work.
Method create_address_channel Create a new underlying gRPC channel for the given address.
Method discard_channel Dispose of an AddressChannel by scheduling its close.
Method get_addr_by_method Return the cached address for a fully-qualified RPC method name.
Method get_addr_from_service_name Resolve a logical service name into a transport address.
Method get_addr_from_stub Resolve the concrete address for a generated service stub class.
Method get_address_interceptors Return the ordered list of interceptors to apply to a channel.
Method get_address_options Compute effective gRPC channel options for a specific address.
Method get_authorization_provider Return the configured AuthorizationProvider.
Method get_channel_by_addr Request an AddressChannel for the given resolved address.
Method get_channel_by_method Convenience to obtain an AddressChannel for an RPC method name. The method resolves the address via get_addr_by_method and then calls get_channel_by_addr to obtain the channel.
Method get_corresponding_operation_service Return an operations service stub for the same address as a generated service stub.
Method get_corresponding_operation_service_alpha Compatibility helper returning the alpha-version operations service stub for the same address as a generated service stub.
Method get_state Nebius Python SDK channels are always ready unless closed.
Async Method get_token Asynchronously fetch an authorization Token.
Method get_token_sync Synchronously fetch an authorization Token.
Method parent_id Return the channel-wide default parent ID used for certain requests.
Method return_channel Return an AddressChannel to the internal pool.
Method run_sync Run an awaitable to completion on the channel's event loop.
Method stream_stream Nebius Python SDK does not support streaming RPCs.
Method stream_unary Nebius Python SDK does not support streaming RPCs.
Method sync_close Synchronously close the channel and wait for graceful shutdown.
Method unary_stream Nebius Python SDK does not support streaming RPCs.
Method unary_unary A method to support using SDK channel as gRPC Channel.
Async Method wait_for_state_change Nebius Python SDK channels are always ready unless closed. This method is provided to satisfy the gRPC Channel interface.
Instance Variable user_agent The user-agent string used by channels created by this Channel instance.
Instance Variable _address_interceptors Undocumented
Instance Variable _address_options Undocumented
Instance Variable _authorization_provider Undocumented
Instance Variable _closed Undocumented
Instance Variable _event_loop Undocumented
Instance Variable _free_channels Undocumented
Instance Variable _global_interceptors Undocumented
Instance Variable _global_interceptors_inner Undocumented
Instance Variable _global_options Undocumented
Instance Variable _gracefuls Undocumented
Instance Variable _max_free_channels_per_address Undocumented
Instance Variable _methods Undocumented
Instance Variable _parent_id Undocumented
Instance Variable _resolver Undocumented
Instance Variable _tasks Undocumented
Instance Variable _tls_credentials Undocumented
Instance Variable _token_bearer Undocumented
def whoami(self, **kwargs: Unpack[RequestKwargs]) -> Request[GetProfileRequest, GetProfileResponse]: (source) ΒΆ

Return a request that fetches the profile for the current credentials.

This is a convenience wrapper around the generated ProfileServiceClient.get method.

Request arguments may be provided as keyword arguments. See nebius.aio.request_kwargs.RequestKwargs for details.

Returns
Request of GetProfileResponseA Request object representing the in-flight RPC. It can be awaited (async) or waited synchronously using its .wait() helpers.