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 –

install_packages(verbose: bool = False)¶

Installs the latest version of the Gretel Transformers package

Parameters: verbose – Will print all package installation messages.

install_transformers()¶

Deprecated: Installs the latest version of the Gretel Transformers package

Prefer install_packages instead.

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>)¶

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

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)