Client

Low level API for interacting directly with the Gretel API

class gretel_client.client.Client(*, host: str, api_key: str = None)

A single client connection to the Gretel API.

detect_entities(records: Union[List[dict], dict]) → List[dict]

Do real-time entity detection from a small batch of records. This function operates outside the scope of a Gretel Project. It uses the Gretel API to do real-time entity detection on JSON records (dicts).

Parameters

records – A single or small list of records.

Returns

A list of dictionaries similar to the records received when consuming from a project stream.

get_project(*, name: str = None, create: bool = False, desc: str = None, display_name: str = None) → gretel_client.projects.Project

Create or get a project. By default, this method will try and fetch an existing Gretel project. If the project does not exist or you are not a member, a NotFound exception will be thrown.

Additionally, you can try and create the project by setting the create flag to True. If this flag is set and the project already exists, Project instance will be returned. If the project does not already exist, Gretel will attempt to create it for you. If the project name is not available then a BadRequest will be returned.

Finally, if you just need a quick project to work with, Gretel can name the project for you by omitting the name:

client.get_project(create=True)
Parameters

  • name – The unique name of the project to get or create.

  • create – If the project does not exist, try and create it. If no project name is provided, create a unique name based on the authenticated user.

  • desc – If project gets created, set the description to this value. This will only get used when a project gets newly created. If the project already exists, nothing will happen with this value.

  • display_name – If project gets created, set the display name to this value. This will be the primary name used when looking at the project in the Gretel Console.

Returns

A Project instance.

Raises

Unauthorized or BadRequest –

get_sample(sample_name: str, as_df=False, **kwargs) → Union[List[Dict], pandas.core.frame.DataFrame]

Returns a sample dataset by key. Use list_samples to get a list of available samples.

Parameters

  • sample_name – The name of the sample to return.

  • as_df – If True, will return the sample dataset as a DataFrame. If the sample record contains nested fields, those fields will be flattened before converting to a DataFrame. Defaults to False.

Returns

A list or DataFrame containing the sample dataset.

Raises

RuntimeError if a DataFrame is requested without pandas being installed. –

install_packages(verbose: bool = False, version: str = 'latest')

Installs the latest version of the Gretel Transformers package

Parameters

  • verbose – Will print all package installation messages.

  • version – Eg: 1.1.0. Determines package version to install. Specifying

  • will ensure the latest version of the package is installed. ("latest") –

install_transformers()

Deprecated: Installs the latest version of the Gretel Transformers package

Prefer install_packages instead.

list_samples(include_details: bool = False, **kwargs) → List[Union[str, dict]]

Gretel provides a number of different sample datasets that can be used to populate projects. This method returns a list of available samples.

Parameters

include_details – If True, the function will return additional sample details. Defult False.

Returns

A list of available sample datasets.

search_projects(count=200, query=None) → List[gretel_client.projects.Project]

Search for projects that you are a member of.

Parameters

  • count – the max number of projects to return

  • query – an optional query string to filter projects on

Returns

A list of Project instances

class gretel_client.client.WriteSummary(success: bool = True, api_errors: List[dict] = <factory>, records_sent: int = 0)

This object is returned from write operations that use threading to batch records to the API.

Note

This object is truthy and can be evaluated as a bool.

api_errors: List[dict] = None

A list of unique errors (as strings) returned from the API if the upload operation was not successful

records_sent: int = 0

Tracks the number of records written to the API

success: bool = True

Whether or not the batch upload of data was successful

gretel_client.client.get_cloud_client(prefix: str, api_key: str) → gretel_client.client.Client

Factory function that creates a Client instance.

Parameters

  • prefix – The API designator, such as “api”

  • api_key – Your Gretel API key

Note

If api_key is “prompt”, and your GRETEL_API_KEY is unset, you will be prompted to enter an api key. If “prompt_always” is set, you will always be prompted for an api key, even if a key is already set on the environment. This is useful for Jupyter Notebooks, etc.

Returns

A Client instance

gretel_client.client.project_from_uri(uri: str) → gretel_client.projects.Project

Get a Project instance from a Gretel URI string, the URI string must have the following format: gretel://[API_KEY]@HOSTNAME/PROJECT

Example:

gretel://grtu12345@api.gretel.cloud/my_project

If your API key is set as an environment variable, you may omit the API key portion of the URI:

gretel://api.gretel.cloud/my_project

Note

If uri is “prompt”, and your GRETEL_URI is unset, you will be prompted to enter a URI. If “prompt_always” is set, you will always be prompted for a project URI, even if a URI is already set on the environment. This is useful for Jupyter Notebooks, etc.

gretel_client.client.temporary_project(client: gretel_client.client.Client)

A temporary project context manager. Create a new project that can be used inside of a “with” statement for temporary purposes. The project will be deleted from Gretel Cloud when the scope is exited.

Example:

with temporary_project(client) as proj:
    proj.send(my_record_list)
    print(proj.entities)