pycarol.carol

class pycarol.carol.Carol(domain: Optional[str] = None, app_name: Optional[str] = None, auth: Optional[Union[ApiKeyAuth, PwdAuth]] = None, connector_id: Optional[str] = None, port: int = 443, verbose: bool = False, organization: Optional[str] = None, environment: Optional[str] = None, host: Optional[str] = None, user: Optional[str] = None, password: Optional[str] = None, api_key: Optional[str] = None, org_level: bool = False, dotenv_path: Optional[Union[str, Path]] = None)[source]

Handles all Carol`s API calls and log user in Carol.

In case all parameters are None, pycarol will try yo find their values in the environment variables. The values are:

  1. CAROLTENANT for domain

  2. CAROLAPPNAME for app_name

  3. CAROLAPPOAUTH for auth

  4. CAROLORGANIZATION for organization

  5. CAROLCONNECTORID for connector_id

  6. CAROL_DOMAIN for environment

  7. CAROLUSER for carol user email

  8. CAROLPWD for user password.

Parameters

  • domain – Tenant name. e.x., domain.carol.ai.

  • app_name – Carol app name.

  • auth – Auth Carol object to handle authentication

  • connector_id – Connector Id

  • port – Port to be used (when running locally it could change)

  • verbose – If True will print the header, method and URL of each API call.

  • organization – Organization domain.

  • environment –

    Which Carol’s environment to use. There are three possible values today.

    1. ’carol.ai’ for the production environment

    2. ’karol.ai’ for the explore environment

    3. ’qarol.ai’ for the QA environment

  • host –

    This will overwrite the host used. Today the host is:

    1. if organization is None, host={domain}.{environment}

    2. else host={organization}.{environment}

    See Carol._set_host.

  • user – User

  • password – User passowrd

  • api_key – Carol’s Api Key

  • org_level – If True, will log-in at organization level.

  • dotenv_path – Path to dotenv file, if loading is required.

Raises

MissingInfoCarolException if there is any mandatory parameter missing –

api_key_details(api_key: str, connector_id: str) → Union[Response, Dict[str, Any], List][source]

Display information about the API key.

Parameters

  • api_key – Carol’s api key

  • connector_id – Connector Id which API key was created.

Returns

Dictionary with API key information.

api_key_revoke(connector_id: str) → Union[Response, Dict[str, Any], List][source]

Revoke API key for the given connector_id.

Parameters

connector_id – Connector Id which API key was created.

Returns

Dictionary with API request response.

call_api(path: str, method: Optional[str] = None, data=None, auth: bool = True, params=None, content_type: Optional[str] = 'application/json', retries: int = 8, session: Optional[Session] = None, backoff_factor: float = 0.5, status_forcelist: Tuple[int, ...] = (502, 503, 504, 524), downloadable: bool = False, method_whitelist: FrozenSet[str] = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'TRACE'}), errors: str = 'raise', extra_headers: Optional[Dict] = None, files: Optional[Dict] = None, prefix_path: str = '/api/', **kwds) → Union[Response, Dict[str, Any], List][source]

Handle all the API calls.

Parameters

  • path – API URI path. e.x. v2/staging/schema.

  • method – Set of uppercased HTTP method verbs that we should call on.

  • data – Same type as :class: Session.request.data Object to send in the body of the request.

  • auth – If API call should be authenticated

  • params – in the query string for the requests.Request.

  • content_type – Content type for the api call

  • retries – Number of retries for the API calls

  • session – It allows you to persist certain parameters across requests.

  • backoff_factor – Backoff factor to apply between attempts. It will sleep for: {backoff factor} * (2 ^ ({retries} - 1)) seconds

  • status_forcelist – A set of integer HTTP status codes that we should force a retry on. A retry is initiated if the request method is in method_whitelist and the response status code is in status_forcelist.

  • downloadable – If the request will return a file to download.

  • method_whitelist – Set of uppercased HTTP method verbs that we should retry on.

  • errors – {‘ignore’, ‘raise’}, default ‘raise’ If ‘raise’, then invalid request will raise an exception If ‘ignore’, then invalid request will return the request response

  • extra_headers – extra headers to be sent.

  • files – Used when uploading files to carol. This will be sent to :class: requests.request

  • prefix_path – Prefix path to be used to create the final url ‘https://{self.host}:{self.port}{prefix_path}{path}.

  • kwds – dict default None Extra parameters to be sent to :class: requests.request

Returns

Dict with API response.

property current_user: Union[Response, Dict[str, Any], List]

Return the current user.

Returns

Carol’s API response payload.

get_current(level: str = 'all') → Dict[str, Any][source]

Get current org/env information.

Parameters

level – Possible Values: “all”: To get organization and environment information. “org”: To get organization information. “env”: To get environment information.

Returns

Dictionary with keys org_Id, org_name, env_id, env_name

Raises

ValueError when level not in 'org', 'env' or 'all' –

get_tenants_for_user() → Union[Response, Dict[str, Any], List][source]

Get all tenants for the current user.

Returns

Dict

issue_api_key(connector_id: Optional[str] = None) → Union[Response, Dict[str, Any], List][source]

Create an API key for a given connector.

Parameters

connector_id – Connector ID to be used when creating the APIkey

Returns

Dictionary with the API key.

switch_context(env_name: Optional[str] = None, env_id: Optional[str] = None, app_name: Optional[str] = None, org_name: Optional[str] = None, org_id: Optional[str] = None) → SwitchContext[source]

Context manager to temporary have access to a second environment.

Parameters

  • env_name – Environment (tenant) name to switch the context to.

  • env_id – Environment (tenant) id to switch the context to.

  • app_name – App name in the target environment to switch the context to. Only needed with using CDS.

Returns

SwitchContext

Examples

from pycarol import Carol, Staging
carol = Carol('B', 'teste', auth=PwdAuth('email@totvs.com.br', 'pwd'), )
with carol.switch_context('A') as carol_tenant_A:
    # fetch parquet from tenant A
    Staging(carol_tenant_A).fetch_parquet(...)
#back to tenant B
switch_environment(env_name: Optional[str] = None, env_id: Optional[str] = None, app_name: Optional[str] = None, org_name: Optional[str] = None, org_id: Optional[str] = None) → Carol[source]

Switch org/environments.

If the user has access to this environment, it will be “logged in” in this new org/environment.

Parameters

  • env_name – Environment (tenant) name to switch the context to.

  • env_id – Environment (tenant) id to switch the context to.

  • app_name – App name in the target environment to switch the context to. Only needed with using CDS.

  • org_name – The organization name to switch context to. If the same keep it None.

  • org_id – The organization id to switch context to. If the same keep it None.

Returns

Carol

switch_org_level()[source]

Switch organization level.

property tenant: Optional[Union[Response, Dict[str, Any], List]]

Return the current tenant.

Returns

Carol’s API response payload.