Skip to content

Eternaltwin

The main client is the entry point for interacting with the Eternaltwin API. It is used to store authorization information and to make requests to the API.

Currently, two implementations of the main client are available:

  • eternaltwin.clients.sync.clients.Eternaltwin — synchronous client using requests to communicate with the Eternaltwin API.
  • eternaltwin.clients.asyncio.clients.Eternaltwin — asynchronous client using aiohttp to communicate with the Eternaltwin API.

Both implementations follow the same interface defined in the section below.

Both main clients use sub-clients to create namespaces for readability and maintainability. The following sub-client is available:

eternaltwin.clients.abc.clients.ClientABC 

ClientABC(client_id: str, client_secret: str, redirect_uri: str, state_key: KeyABC, *, url: str = None, scheme: str = 'http', host: str = None, port: str | int = None, prefix: str = '/', timeout: int = 5, verify_ssl: bool = True, allow_redirects: bool = False)

Bases: ABC

Base class for client handling communication with EternalTwin.

Parameters:

Name Type Description Default
client_id str

The client ID obtained from EternalTwin when registering the app.

 required
client_secret str

The client secret obtained from EternalTwin when registering the app.

 required
redirect_uri str

The redirect URI registered with EternalTwin for the app.

 required
state_key KeyABC

The key used to sign and verify state tokens.

 required
url str

The base URL for the EternalTwin API. If not provided, scheme, host, port, and prefix should be provided instead.

 None
scheme str

The URL scheme to use (e.g., "http" or "https"). Required if url is not provided.

 'http'
host str

The URL host to use (e.g., "eternaltwin.org"). Required if url is not provided.

 None
port str | int

The URL port to use. Required if url is not provided.

 None
prefix str

The URL prefix to use. Default to /, only used if url is not provided.

 '/'
timeout int

The timeout for API requests in seconds. Default is 5 seconds.

 5
verify_ssl bool

Whether to verify SSL certificates for API requests. Default is True.

 True
allow_redirects bool

Whether to allow redirects for API requests. Default is False.

 False

authorization_url 

authorization_url(state: str) -> str

Create an OAuth authorization request URL.

The result URL contains all the information required for the user to grant the requested authorization and then call back the app and resume handling with the provided state.

token abstractmethod 

token(authorization_code: str) -> Token | Awaitable[Token]

Retrieve a token using the provided authorization code.

generate_state 

generate_state(expiration: int = 600, nonce: str = None) -> str

Generate a new state using the client's URL and key.

Parameters:

Name Type Description Default
expiration int

Expiration time in seconds. Default to 600 seconds.

 600
nonce str

An optional nonce value used to guarantee the state to be unique. If not provided, a random one will be generated.

 None
Return

str The generated state encoded as a JWT.

validate_state 

validate_state(state: str, expected: str = None) -> None

Validate the state received from the authorization server.

An expected state can be provided to check if the state received from the authorization server matches the expected one.

Raises:

Type Description
InvalidStateError

If action or authorization server does not match, the JWT is expired, or the received state does not match the expected one (if provided).

eternaltwin.clients.sync.clients.Eternaltwin 

Eternaltwin(client_id: str, client_secret: str, redirect_uri: str, state_key: KeyABC, *, url: str = None, scheme: str = 'http', host: str = None, port: str | int = None, prefix: str = '/', timeout: int = 5, verify_ssl: bool = True, allow_redirects: bool = False)

Bases: ClientABC

Synchronous implementation of ClientABC using requests.

eternaltwin.clients.sync.clients.Eternaltwin.get 

get(endpoint: str, raise_on_error: bool = True, token: Token = None, **kwargs: Any) -> Response

Helper to make a GET request to EternalTwin.

eternaltwin.clients.sync.clients.Eternaltwin.post 

post(endpoint: str, raise_on_error: bool = True, token: Token = None, **kwargs: Any) -> Response

Helper to make a POST request to EternalTwin.

eternaltwin.clients.sync.clients.Eternaltwin.token 

token(authorization_code: str) -> Token

Retrieve a token using the provided authorization code.

eternaltwin.clients.asyncio.clients.Eternaltwin 

Eternaltwin(client_id: str, client_secret: str, redirect_uri: str, state_key: KeyABC, *, url: str = None, scheme: str = 'http', host: str = None, port: str | int = None, prefix: str = '/', timeout: int = 5, verify_ssl: bool = True, allow_redirects: bool = False)

Bases: ClientABC

Asynchronous implementation of ClientABC using aiohttp.

eternaltwin.clients.asyncio.clients.Eternaltwin.get async 

get(endpoint: str, raise_on_error: bool = True, token: Token = None, **kwargs: Any) -> Response

Helper to make a GET request to EternalTwin.

eternaltwin.clients.asyncio.clients.Eternaltwin.post async 

post(endpoint: str, raise_on_error: bool = True, token: Token = None, **kwargs: Any) -> Response

Helper to make a POST request to EternalTwin.

eternaltwin.clients.asyncio.clients.Eternaltwin.token async 

token(authorization_code: str) -> Token

Retrieve a token using the provided authorization code.