qcs-api-client-common 0.17.4

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import collections.abc
import typing
from qcs_api_client_common import QcsApiClientError

API_URL_VAR: typing.Final = 'QCS_SETTINGS_APPLICATIONS_API_URL'
DEFAULT_API_URL: typing.Final = 'https://api.qcs.rigetti.com'
DEFAULT_GRPC_API_URL: typing.Final = 'https://grpc.qcs.rigetti.com'
DEFAULT_PROFILE_NAME: typing.Final = 'default'
DEFAULT_QUILC_URL: typing.Final = 'tcp://127.0.0.1:5555'
DEFAULT_QVM_URL: typing.Final = 'http://127.0.0.1:5000'
DEFAULT_SECRETS_PATH: typing.Final = '~/.qcs/secrets.toml'
DEFAULT_SETTINGS_PATH: typing.Final = '~/.qcs/settings.toml'
GRPC_API_URL_VAR: typing.Final = 'QCS_SETTINGS_APPLICATIONS_GRPC_URL'
PROFILE_NAME_VAR: typing.Final = 'QCS_PROFILE_NAME'
QUILC_URL_VAR: typing.Final = 'QCS_SETTINGS_APPLICATIONS_QUILC_URL'
QVM_URL_VAR: typing.Final = 'QCS_SETTINGS_APPLICATIONS_QVM_URL'
SECRETS_PATH_VAR: typing.Final = 'QCS_SECRETS_FILE_PATH'
SETTINGS_PATH_VAR: typing.Final = 'QCS_SETTINGS_FILE_PATH'
@typing.final
class AuthServer:
    r"""
    OAuth 2.0 authorization server.
    """
    @property
    def client_id(self) -> builtins.str:
        r"""
        OAuth 2.0 client id.
        """
    @client_id.setter
    def client_id(self, value: builtins.str) -> None:
        r"""
        OAuth 2.0 client id.
        """
    @property
    def issuer(self) -> builtins.str:
        r"""
        OAuth 2.0 issuer URL.
        
        This is the base URL of the identity provider.
        For Okta, this usually looks like `https://example.okta.com/oauth2/default`.
        For Cognito, it might look like `https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example`.
        
        Note that this is technically distinct from the `issuer` field in [`OidcDiscovery`],
        which is the canonical URI that the identity provider uses to sign and validate tokens,
        but the OpenID specification requires that they match exactly,
        and that they match the `iss` claim in Tokens issued by this identity provider.
        """
    @issuer.setter
    def issuer(self, value: builtins.str) -> None:
        r"""
        OAuth 2.0 issuer URL.
        
        This is the base URL of the identity provider.
        For Okta, this usually looks like `https://example.okta.com/oauth2/default`.
        For Cognito, it might look like `https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example`.
        
        Note that this is technically distinct from the `issuer` field in [`OidcDiscovery`],
        which is the canonical URI that the identity provider uses to sign and validate tokens,
        but the OpenID specification requires that they match exactly,
        and that they match the `iss` claim in Tokens issued by this identity provider.
        """
    @property
    def scopes(self) -> typing.Optional[builtins.list[builtins.str]]:
        r"""
        OAuth 2.0 scopes to request during authorization requests.
        If not specified, `supported_scopes` from the discovery document hosted at `issuer` will be used.
        The scope `openid` is always requested, even if not present in this list.
        """
    @scopes.setter
    def scopes(self, value: typing.Optional[builtins.list[builtins.str]]) -> None:
        r"""
        OAuth 2.0 scopes to request during authorization requests.
        If not specified, `supported_scopes` from the discovery document hosted at `issuer` will be used.
        The scope `openid` is always requested, even if not present in this list.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, client_id: builtins.str, issuer: builtins.str, scopes: typing.Optional[typing.Sequence[builtins.str]] = None) -> AuthServer: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def default() -> AuthServer: ...

@typing.final
class ClientConfiguration:
    r"""
    A configuration suitable for use as a QCS API Client.
    
    This configuration can be constructed in a few ways.
    
    The most common way is to use [`ClientConfiguration::load_default`]. This will load the
    configuration associated with your default QCS profile.
    
    When loading your config, any values set by environment variables will override the values in
    your configuration files.
    
    You can also build a configuration from scratch using [`ClientConfigurationBuilder`]. Using a
    builder bypasses configuration files and environment overrides.
    """
    @property
    def api_url(self) -> builtins.str:
        r"""
        The URL for the QCS REST API.
        """
    @property
    def grpc_api_url(self) -> builtins.str:
        r"""
        The URL for the QCS gRPC API.
        """
    @property
    def quilc_url(self) -> builtins.str:
        r"""
        The URL of the quilc server.
        """
    @property
    def qvm_url(self) -> builtins.str:
        r"""
        The URL of the QVM server.
        """
    def __new__(cls, api_url: typing.Optional[builtins.str] = None, grpc_api_url: typing.Optional[builtins.str] = None, quilc_url: typing.Optional[builtins.str] = None, qvm_url: typing.Optional[builtins.str] = None, oauth_session: typing.Optional[OAuthSession] = None) -> ClientConfiguration: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    @staticmethod
    def builder() -> ClientConfigurationBuilder: ...
    def get_bearer_access_token(self) -> SecretAccessToken:
        r"""
        Gets the `Bearer` access token, refreshing it if it is expired.
        
        # Errors
        
        - Raises a `TokenError` if there's a problem providing the token.
        """
    def get_bearer_access_token_async(self) -> collections.abc.Awaitable[SecretAccessToken]: ...
    def get_oauth_session(self) -> OAuthSession:
        r"""
        Get the configured [`OAuthSession`].
        
        # Errors
        
        - Raises a `TokenError` if there is a problem fetching the tokens.
        """
    def get_oauth_session_async(self) -> collections.abc.Awaitable[OAuthSession]: ...
    @staticmethod
    def load_default() -> ClientConfiguration: ...
    @staticmethod
    def load_default_with_login() -> ClientConfiguration: ...
    @staticmethod
    def load_profile(profile_name: builtins.str) -> ClientConfiguration: ...

@typing.final
class ClientConfigurationBuilder:
    r"""
    Builder for [`ClientConfiguration`](struct.ClientConfiguration.html).
    """
    @property
    def api_url(self) -> typing.Optional[builtins.str]:
        r"""
        The URL for the QCS REST API.
        """
    @api_url.setter
    def api_url(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        The URL for the QCS REST API.
        """
    @property
    def grpc_api_url(self) -> typing.Optional[builtins.str]:
        r"""
        The URL for the QCS gRPC API.
        """
    @grpc_api_url.setter
    def grpc_api_url(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        The URL for the QCS gRPC API.
        """
    @property
    def oauth_session(self) -> typing.Optional[typing.Optional[TokenDispatcher]]:
        r"""
        Provides a single, semi-shared access to user credential tokens.
        
        Note that the tokens are *not* shared when the `ClientConfiguration` is created multiple
        times, e.g. through [`ClientConfiguration::load_default`].
        """
    @oauth_session.setter
    def oauth_session(self, value: typing.Optional[OAuthSession]) -> None:
        r"""
        The [`OAuthSession`] to use to authenticate with the QCS API.
        
        When set to [`None`], the configuration will not manage an OAuth Session, and access to the
        QCS API will be limited to unauthenticated routes.
        """
    @property
    def quilc_url(self) -> typing.Optional[builtins.str]:
        r"""
        The URL of the quilc server.
        """
    @quilc_url.setter
    def quilc_url(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        The URL of the quilc server.
        """
    @property
    def qvm_url(self) -> typing.Optional[builtins.str]:
        r"""
        The URL of the QVM server.
        """
    @qvm_url.setter
    def qvm_url(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        The URL of the QVM server.
        """
    def __new__(cls) -> ClientConfigurationBuilder: ...
    def build(self) -> ClientConfiguration: ...

class ClientConfigurationBuilderError(ConfigurationError):
    r"""
    Unable to build a configuration due to missing or improper values.
    """
    ...

@typing.final
class ClientCredentials:
    r"""
    A pair of Client ID and Client Secret, used to request an OAuth Client Credentials Grant
    """
    @property
    def client_id(self) -> builtins.str:
        r"""
        The client ID
        """
    @property
    def client_secret(self) -> ClientSecret:
        r"""
        The client secret.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, client_id: builtins.str, client_secret: builtins.str) -> ClientCredentials: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class ClientSecret:
    r"""
    The [OAuth2 Client Credentials](https://oauth.net/2/grant-types/client-credentials/) secret.
    """
    @property
    def is_empty(self) -> builtins.bool:
        r"""
        Check if the secret is an empty value
        """
    @property
    def secret(self) -> builtins.str:
        r"""
        Get the inner secret contents, which removes the protection against accidentally exposing the value.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, value: builtins.str) -> ClientSecret: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

class ConfigurationError(QcsApiClientError):
    r"""
    Base exception type for configuration errors.
    """
    ...

@typing.final
class ExternallyManaged:
    r"""
    A struct that manages access tokens by utilizing a user-provided refresh function.
    
    The [`ExternallyManaged`] struct allows users to define custom logic for
    fetching or refreshing access tokens.
    """
    def __new__(cls, refresh_function: collections.abc.Callable[[AuthServer], str]) -> ExternallyManaged: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

class LoadError(ConfigurationError):
    r"""
    Errors that can occur when loading a configuration.
    """
    ...

@typing.final
class OAuthSession:
    r"""
    Manages the `OAuth2` authorization process and token lifecycle for accessing the QCS API.
    
    This struct encapsulates the necessary information to request an access token
    from an authorization server, including the `OAuth2` grant type and any associated
    credentials or payload data.
    
    # Fields
    
    * `payload` - The `OAuth2` grant type and associated data that will be used to request an access token.
    * `access_token` - The access token currently in use, if any. If no token has been provided or requested yet, this will be `None`.
    * `auth_server` - The authorization server responsible for issuing tokens.
    """
    @property
    def access_token(self) -> typing.Optional[SecretAccessToken]:
        r"""
        The access token that is currently in use. None if no token has been requested yet.
        """
    @property
    def auth_server(self) -> AuthServer:
        r"""
        The [`AuthServer`] that issues the tokens.
        """
    @property
    def payload(self) -> RefreshToken | ClientConfiguration | ExternallyManaged | PkceFlow:
        r"""
        The grant type to use to request an access token.
        """
    def __new__(cls, payload: RefreshToken | ClientConfiguration | ExternallyManaged | PkceFlow, auth_server: AuthServer, access_token: typing.Optional[SecretAccessToken] = None) -> OAuthSession: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """
    def request_access_token(self) -> SecretAccessToken: ...
    def request_access_token_async(self) -> collections.abc.Awaitable[SecretAccessToken]: ...
    def validate(self) -> SecretAccessToken: ...

@typing.final
class PkceFlow:
    r"""
    The Access (Bearer) and refresh (if available) tokens from a PKCE login.
    """
    @property
    def access_token(self) -> SecretAccessToken:
        r"""
        The access token.
        """
    @property
    def refresh_token(self) -> typing.Optional[RefreshToken]:
        r"""
        The refresh token, if available.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, auth_server: AuthServer) -> PkceFlow: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class RefreshToken:
    r"""
    A single type containing an access token and an associated refresh token.
    """
    @property
    def refresh_token(self) -> SecretRefreshToken:
        r"""
        The token used to refresh the access token.
        """
    @refresh_token.setter
    def refresh_token(self, value: SecretRefreshToken) -> None:
        r"""
        The token used to refresh the access token.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, refresh_token: SecretRefreshToken) -> RefreshToken: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class SecretAccessToken:
    r"""
    An [OAuth 2.0 access token][https://oauth.net/2/access-tokens/] that is used to authenticate requests to the QCS API as a `Bearer` token.
    """
    @property
    def is_empty(self) -> builtins.bool:
        r"""
        Check if the secret is an empty value
        """
    @property
    def secret(self) -> builtins.str:
        r"""
        Get the inner secret contents, which removes the protection against accidentally exposing the value.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, value: builtins.str) -> SecretAccessToken: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class SecretRefreshToken:
    r"""
    An [OAuth 2.0 refresh token][https://oauth.net/2/refresh-tokens/] that is used to obtain a new [`SecretAccessToken`].
    """
    @property
    def is_empty(self) -> builtins.bool:
        r"""
        Check if the secret is an empty value
        """
    @property
    def secret(self) -> builtins.str:
        r"""
        Get the inner secret contents, which removes the protection against accidentally exposing the value.
        """
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __new__(cls, value: builtins.str) -> SecretRefreshToken: ...
    def __repr__(self) -> builtins.str:
        r"""
        Implements `__repr__` for Python in terms of the Rust
        [`Debug`](std::fmt::Debug) implementation.
        """

@typing.final
class TokenDispatcher:
    r"""
    A wrapper for [`OAuthSession`] that provides thread-safe access to the inner tokens.
    """
    ...

class TokenError(ConfigurationError):
    r"""
    Errors that can occur when managing authorization tokens.
    """
    ...

def get_bearer_access_token(configuration: ClientConfiguration) -> SecretAccessToken:
    r"""
    Gets the `Bearer` access token, refreshing it if it is expired.
    
    # Errors
    
    Raises a `TokenError` if there's a problem providing the token.
    """

def get_bearer_access_token_async(configuration: ClientConfiguration) -> collections.abc.Awaitable[SecretAccessToken]:
    r"""
    Gets the `Bearer` access token, refreshing it if it is expired.
    
    # Errors
    
    Raises a `TokenError` if there's a problem providing the token.
    """

def get_oauth_session(tokens: typing.Optional[TokenDispatcher]) -> OAuthSession: ...

def get_oauth_session_async(tokens: typing.Optional[TokenDispatcher]) -> collections.abc.Awaitable[OAuthSession]: ...

def request_access_token(session: OAuthSession) -> SecretAccessToken:
    r"""
    Request and return an updated access token using these credentials.
    
    # Errors
    
    Raises a `TokenError` if there's a problem providing the token.
    """

def request_access_token_async(session: OAuthSession) -> collections.abc.Awaitable[SecretAccessToken]:
    r"""
    Request and return an updated access token using these credentials.
    
    # Errors
    
    Raises a `TokenError` if there's a problem providing the token.
    """