nebius.aio.token.renewable.Bearer

class documentation

class Bearer(ParentBearer): (source)

Constructor: Bearer(source, max_retries, lifetime_safe_fraction, initial_retry_timeout, ...)

Bearer that keeps a shared cached token refreshed in the background.

The Bearer wraps another ParentBearer and starts a background task on the first fetch. The cached token is refreshed proactively based on the token's expiration and the configured lifetime_safe_fraction.

The bearer supports two renewal modes for fetch requests:

asynchronous: trigger a background renewal and wait for the

cached token to become fresh;
synchronous: block until a new token has been fetched (or until

a specified request timeout elapses).

Example

Construct a bearer and use it to initialize the SDK:

from nebius.sdk import SDK
from nebius.aio.token.renewable import Bearer
from nebius.aio.token.static import Bearer as StaticBearer

some_bearer = StaticBearer("my-static-token") # for illustrative purposes

# Wrap some bearer with renewal
renewable_bearer = Bearer(some_bearer)

sdk = SDK(credentials=renewable_bearer)

Parameters
source	The inner bearer used to actually fetch tokens.
max_retries	Maximum number of retry attempts performed by receivers created by `receiver`.
lifetime_safe_fraction	Fraction of remaining token lifetime after which a refresh will be scheduled (e.g. `0.9` refreshes when 90% of lifetime has passed).
initial_retry_timeout	Initial retry delay used in a backoff when a refresh fails.
max_retry_timeout	Maximum retry delay cap.
retry_timeout_exponent	Exponential backoff base used to grow retry delays between attempts.
refresh_request_timeout	Timeout used for individual refresh requests when contacting the inner bearer.

Method	`__init__`	Initialize the renewable bearer.
Method	`bg_task`	Run a coroutine without awaiting or tracking, and log exceptions.
Async Method	`close`	Close the bearer, cancelling background tasks and closing source.
Async Method	`fetch`	Fetch a token, renewing it if necessary.
Method	`is_renewal_required`	Return `True` when a renewal should be performed.
Method	`receiver`	Return a per-request `Receiver` bound to this bearer.
Method	`request_renewal`	Request a token renewal.
Method	`stop`	Stop the renewal background task and unblock any waiters.
Property	`wrapped`	Return the wrapped bearer.
Async Method	`_fetch_once`	Fetch a single token from the inner bearer.
Async Method	`_run`	Background loop that refreshes the token periodically.
Instance Variable	`_break_previous_attempt`	Undocumented
Instance Variable	`_cache`	Undocumented
Instance Variable	`_initial_retry_timeout`	Undocumented
Instance Variable	`_is_fresh`	Undocumented
Instance Variable	`_is_stopped`	Undocumented
Instance Variable	`_lifetime_safe_fraction`	Undocumented
Instance Variable	`_max_retries`	Undocumented
Instance Variable	`_max_retry_timeout`	Undocumented
Instance Variable	`_refresh_request_timeout`	Undocumented
Instance Variable	`_refresh_task`	Undocumented
Instance Variable	`_renew_requested`	Undocumented
Instance Variable	`_renew_synchronous_options`	Undocumented
Instance Variable	`_renew_synchronous_timeout`	Undocumented
Instance Variable	`_renewal_attempt`	Undocumented
Instance Variable	`_renewal_future`	Undocumented
Instance Variable	`_retry_timeout_exponent`	Undocumented
Instance Variable	`_source`	Undocumented
Instance Variable	`_synchronous_can_proceed`	Undocumented
Instance Variable	`_tasks`	Undocumented

Inherited from Bearer:

Property name Optional human-readable name for the bearer.

def __init__(self, source: ParentBearer, max_retries: int = 2, lifetime_safe_fraction: float = 0.9, initial_retry_timeout: timedelta = timedelta(seconds=1), max_retry_timeout: timedelta = timedelta(minutes=1), retry_timeout_exponent: float = 1.5, refresh_request_timeout: timedelta = timedelta(seconds=5)): (source) ¶

Initialize the renewable bearer.

def bg_task(self, coro: Awaitable[T]) -> Task[None]: (source) ¶

Run a coroutine without awaiting or tracking, and log exceptions.

The coroutine is scheduled as a background task and any unhandled exception is logged. The returned task is tracked so it can be cancelled during shutdown.

Parameters
coro:`Awaitable[T]`	Awaitable to run in a fire-and-forget task.
Returns
`Task[None]`	The created `asyncio.Task` instance.

async def close(self, grace: float | None = None): (source) ¶

overrides nebius.aio.token.token.Bearer.close

Close the bearer, cancelling background tasks and closing source.

Parameters
grace:`float \| None`	Optional graceful shutdown timeout forwarded to the inner bearer's `close` method.

async def fetch(self, timeout: float | None = None, options: dict[str, str] | None = None) -> Token: (source) ¶

Fetch a token, renewing it if necessary.

The fetch operation may trigger a background renewal or perform a synchronous renewal based on the provided options. When a synchronous renewal is requested the caller waits for a new token to be fetched (or for the request timeout to expire).

Parameters
timeout:`float \| None`	Optional timeout in seconds for waiting for a token.
options:`dict[str, str] \| None`	Optional mapping of request flags. Recognized keys include: `OPTION_RENEW_REQUIRED`: force a renewal `OPTION_RENEW_SYNCHRONOUS`: request synchronous renewal `OPTION_RENEW_REQUEST_TIMEOUT`: override synchronous renewal request timeout (as a string float) `OPTION_REPORT_ERROR`: return errors from renewal to the caller via an exception
Returns
`Token`	A fresh `Token` instance.
Raises
`RenewalError`	when the cache remains empty after renewal.

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

Return True when a renewal should be performed.

Renewal is required when there is no cached token or when an explicit renewal request has been signalled.

def receiver(self) -> Receiver: (source) ¶

overrides nebius.aio.token.token.Bearer.receiver

Return a per-request Receiver bound to this bearer.

The returned receiver will use the bearer's configuration for retry behaviour. :returns: A Receiver instance.

def request_renewal(self): (source) ¶

Request a token renewal.

If the bearer is not stopped this clears the freshness flag and signals the background loop to perform a renewal as soon as possible.

def stop(self): (source) ¶

Stop the renewal background task and unblock any waiters.

This method marks the bearer as stopped, clears the freshness event and signals any waiting synchronous renewal attempts to unblock. It is safe to call multiple times.

@property
wrapped: ParentBearer | None = (source) ¶

overrides nebius.aio.token.token.Bearer.wrapped

Return the wrapped bearer.

async def _fetch_once(self) -> Token: (source) ¶

Fetch a single token from the inner bearer.

This helper performs a single attempt to obtain a token from self._source while cooperating with the synchronous-renewal signalling primitives. It returns the received token and updates the cached token on success.

async def _run(self): (source) ¶

Background loop that refreshes the token periodically.

The loop waits either until a scheduled retry timeout elapses or until an explicit renewal request is signalled. On errors a backoff strategy is applied before the next attempt.

_break_previous_attempt = (source) ¶

Undocumented

_cache: Token | None = (source) ¶

Undocumented

_initial_retry_timeout = (source) ¶

Undocumented

_is_fresh = (source) ¶

Undocumented

_is_stopped = (source) ¶

Undocumented

_lifetime_safe_fraction = (source) ¶

Undocumented