ds_stoa.manager.client¶

manager.client.py

This module contains the Stoa class, which is a core component of our package. The Stoa class offers functionality for fetching, signing, authenticating, and ordering messages, which are essential operations for communication and data exchange within our system.

Attributes¶

LOGGER

Classes¶

StoaClient

The Stoa class provides methods for handling messages within our system.

Functions¶

`oauth2`(→ str)	Authenticates an application and retrieves an access token.
`rest`(→ str)	Authenticates a user and retrieves an access token.
`fetch`(→ pandas.DataFrame)	Fetch data from a collection of pre-signed URLs in
`order`(→ List[str])	Send order request to Stoa API.
`sign`(→ str)	Generate a pre-signed URL for accessing data in the
`ensure_authenticated`(→ Callable[Ellipsis, Any])

Module Contents¶

ds_stoa.manager.client.oauth2(client_id: str, client_secret: str) → str¶

Authenticates an application and retrieves an access token.

Parameters:

client_id (str) – The Client ID.
client_secret (str) – The Client Secret.

Returns:

An access token indicating successful authentication.

Return type:

str

Example:

>>> oauth2('client_id', 'client_secret')
'access_token_value'

ds_stoa.manager.client.rest(email: str, password: str) → str¶

Authenticates a user and retrieves an access token.

Parameters:

email (str) – The email of the user.
password (str) – The password of the user.

Returns:

An access token indicating successful authentication.

Return type:

str

Example:

>>> rest('user@example.com', 'secret')
'access_token_value'

ds_stoa.manager.client.fetch(pre_signed_urls: Dict) → pandas.DataFrame¶

Fetch data from a collection of pre-signed URLs in parallel and consolidate into a single DataFrame.

Parameters:: pre_signed_urls (Dict[str, str]) – A dictionary where keys are identifiers and values are pre-signed URLs.
Returns:: A consolidated Pandas DataFrame containing data from all fetched URLs.
Return type:: pd.DataFrame

Example:

pre_signed_urls = {
    "file1": "http://example.com/data1.parquet",
    "file2": "http://example.com/data2.parquet",
}
dataframe = fetch(pre_signed_urls)

ds_stoa.manager.client.order(token: str, params: Dict) → List[str]¶

Send order request to Stoa API.

Parameters:

token – Authentication token required for the API request.
params – Parameters for the order request, such as product ID and quantity.

Returns:

A dictionary containing the response from the Stoa API.

Example:

>>> order(token=token, params=params)
["12345.snappy.parquet", "67890.snappy.parquet"]

ds_stoa.manager.client.sign(token: str, params: Dict) → str¶

Generate a pre-signed URL for accessing data in the GraspDP datalake.

Parameters:

token – Authentication token required for generating the pre-signed URL.
params – Parameters for the request, typically including identifiers for the data to be accessed.

Returns:

A string containing the pre-signed URL.

Raises:

ValueError – If the pre-signed URL is not found.

Example::

>>> sign(token=token, params=params)
"https://fmdp.io/stoa-dev/sign/12345"

ds_stoa.manager.client.LOGGER¶

ds_stoa.manager.client.ensure_authenticated(method) → Callable[Ellipsis, Any]¶

class ds_stoa.manager.client.StoaClient(authentication: Literal['rest', 'oauth2'], product_group_name: str, product_name: str, workspace: Literal['apps', 'cart'], owner_id: str, version: str = '1.0', offset: int = 0, limit: int = 20, ascending: bool = False, email: str | None = None, password: str | None = None, client_id: str | None = None, client_secret: str | None = None)¶

The Stoa class provides methods for handling messages within our system. These methods include operations for fetching, signing, authenticating, and ordering messages.

property token: str¶

Token getter that retrieves the current access token.

Returns:: The access token.
Raises:: ValueError – If the access token is missing.

property order_ids: List[str]¶

Order IDs getter that retrieves the current list of order IDs.

Returns:: List of order IDs.
Raises:: ValueError – If no order IDs are found.

property signatures: Dict¶

Signatures getter that retrieves the current dictionary of signatures.

Returns:: Dictionary of signatures.
Raises:: ValueError – If no signatures are found.

authenticate() → None¶

Authenticates a message to verify its origin. This method is used to check if a message came from a trusted source before it is processed by the system.

Returns:: The access token for the authenticated request.
Return type:: str
Raises:: NotImplementedError – If the authentication method is invalid.

example::

>>> stoa = StoaClient(**params)
>>> stoa.authenticate()
>>> assert stoa.token

is_authenticated() → bool¶

Checks if a message is authenticated. This method is used to verify that a message has been authenticated before it is processed by the system.

Returns:: True if the message is authenticated, False otherwise.
Return type:: bool

example::

>>> stoa = StoaClient(**params)
>>> stoa.authenticate()
>>> assert stoa.is_authenticated()

order() → List[str]¶

Orders a message based on predefined rules. This method is used to sort or arrange messages according to certain criteria before they are processed by the system.

Returns:: Ordered keys.
Return type:: List
Raises:: ValueError – If the workspace is invalid.

example::

>>> stoa = StoaClient(**params)
>>> stoa.order()
>>> assert stoa.order_ids

sign() → Dict¶

Signs a message to ensure its integrity and authenticity. This method is used to add a layer of security to our messages, making sure they are not tampered with during transit.

Returns:: The pre-signed URLs for the messages.
Return type:: Dict
Raises:: ValueError – If the order IDs are missing.

example::

>>> stoa = StoaClient(**params)
>>> stoa.order()
>>> stoa.sign()
>>> assert stoa.signatures

fetch(format: Literal['json', 'dataframe']) → List[Dict] | pandas.DataFrame¶

Fetches a message from a predefined source. This method is responsible for retrieving messages that are to be processed by the system.

Parameters:: format – The format in which to return the fetched data.
Returns:: The fetched data in the specified format.
Return type:: List[Dict]
Raises:: ValueError – If the format is invalid.

example::

>>> stoa = StoaClient(**params)
>>> stoa.fetch(format="json")