Projects

High level API for interacting with a Gretel Project

class gretel_client.projects.projects.Project(*, name: str, project_id: str, project_guid: str | None = None, desc: str | None = None, display_name: str | None = None, runner_mode: str | RunnerMode | None = None, session: ClientConfig | None = None, cluster_guid: str | None = None)

Represents a Gretel project. In general you should not init this class directly, but always make use of the factory methods get_project, create_project, get_or_create_project etc.

Parameters:

  • name – The unique name of the project. This is either set by you or auto managed by Gretel

  • project_id – The unique project id of your project. This is managed by gretel and never changes.

  • desc – A short description of the project

  • display_name – The main display name used in the Gretel Console for your project

  • session – The client session to use for API interactions, or None to use the default session.

property artifacts: List[dict]

Returns a list of project artifacts.

property as_dict: dict

Returns a dictionary representation of the project.

create_model_obj(model_config: str | Path | dict, data_source: str | DataFrame | None = None, ref_data: str | Dict[str, str] | List[str] | Tuple[str] | DataFrame | List[DataFrame] | None = None) → Model

Creates a new model object. This will not submit the model to Gretel’s cloud API. Please refer to the Model docs for more information detailing how to submit the model.

Parameters:

  • model_config – Specifies a model config. For more information about model configs, please refer to our doc site, https://docs.gretel.ai/reference/model-configurations.

  • data_source – Defines the model data_source. If the model_config already has a data_source defined, this property will override the existing one.

  • ref_data – An Optional str, dict, dataframe or list of reference data sources to upload for the job.

delete(*args, **kwargs)

Deletes a project. After the project has been deleted, functions relying on a project will fail with a GretelProjectError exception.

Note: Deleting projects is asynchronous. It may take a few seconds for the project to be deleted by Gretel services.

delete_artifact(key: str)

Deletes a project artifact.

Parameters:

key – Artifact key to delete.

get_artifact_handle(key: str) → BinaryIO

Returns a reference to a remote artifact that can be used to read binary data within a context manager

>>> with job.get_artifact_handle("report_json") as file:
...   print(file.read())
Parameters:

key – Artifact key to download.

Returns:

a file like object

Returns a link to download a project artifact.

Parameters:

key – Project artifact key to generate download url for.

Returns:

A signed URL that may be used to download the given project artifact.

get_console_url() → str

Returns web link to access the project from Gretel’s console.

get_model(model_id: str) → Model

Lookup and return a Project Model by it’s model_id.

Parameters:

model_id – The model_id to lookup

info() → dict

Return details about the project.

search_models(factory: ~typing.Type[~gretel_client.projects.projects.MT] = <class 'gretel_client.projects.models.Model'>, limit: int = 100, skip: int | None = None, model_name: str = '', sort_by: str | None = None, sort_field: str | None = None, status: str | None = None) → Iterator[MT]

Search for project models.

Parameters:

  • factory – Determines what type of Model representation is returned. If Model is passed, a Model will be returned. If dict is passed, a dictionary representation of the search results will be returned.

  • limit – Limits the number of project models to return

  • skip – Number of models to skip before applying limit

  • model_name – Name of the model to try and match on (partial match)

  • sort_by – Direction to sort. Uses ‘asc’ if not provided

  • sort_field – Field to sort on. Uses ‘last_modified’ if not provided

  • status – Filter to models with specific status.

upload_artifact(artifact_path: Path | str | DataFrame, _validate: bool = True, _artifacts_handler: ArtifactsHandler | None = None) → str

Resolves and uploads the data source specified in the model config.

Returns:

A Gretel artifact key.

gretel_client.projects.projects.create_or_get_unique_project(*, name: str, desc: str | None = None, display_name: str | None = None, session: ClientConfig | None = None, runner_mode: str | RunnerMode | None = None, hybrid_environment_guid: str | None = None) → Project

Helper function that provides a consistent experience for creating and fetching a project with the same name. Given a name of a project, this helper will fetch the current user’s ID and use that as a suffix in order to create a project name unique to that user. Once the project is created, if it can be fetched, it will not be re-created over and over again.

Parameters:

  • name – The name of the project, which will have the User’s ID appended to it automatically.

  • desc – Description of the project.

  • display_name – If None, the display name will be set equal to the value of name _before_ the user ID is appended.

  • session – The client session to use, or None to use the default client session.

  • runner_mode – The runner_mode for the project, one of either "cloud" or "hybrid".

  • hybrid_environment_guid – The guid of the hybrid environment to associate with the project, when the runner_mode is of type “hybrid”.

Note

The desc and display_name parameters will only be used when the project is first created. If the project already exists, these params will have no affect.

gretel_client.projects.projects.create_project(*, name: str | None = None, desc: str | None = None, display_name: str | None = None, session: ClientConfig | None = None, runner_mode: str | RunnerMode | None = None, hybrid_environment_guid: str | None = None) → Project

Excplit project creation. This function will simply call the API endpoint and will raise any HTTP exceptions upstream.

gretel_client.projects.projects.get_project(*, name: str | None = None, create: bool = False, desc: str | None = None, display_name: str | None = None, runner_mode: str | RunnerMode | None = None, session: ClientConfig | None = None, hybrid_environment_guid: str | None = None) → Project

Used to get or create a Gretel project.

Parameters:

  • name – The unique name of the project. This is either set by you or auto managed by Gretel.

  • create – If create is set to True the function will create the project if it doesn’t exist.

  • project_id – The unique project id of your project. This is managed by gretel and never changes.

  • desc – A short description of the project

  • display_name – The main display name used in the Gretel Console for your project

  • session – the client session to use, or None to use the default session.

Returns:

A project instance.

gretel_client.projects.projects.search_projects(limit: int = 200, query: str | None = None, *, session: ClientConfig | None = None) → List[Project]

Searches for project.

Parameters:

  • limit – The max number of projects to return.

  • query – String filter applied to project names.

  • session – Can be used to override local Gretel config.

Returns:

A list of projects.

gretel_client.projects.projects.tmp_project(*, session: ClientConfig | None = None, runner_mode: str | RunnerMode | None = None, hybrid_environment_guid: str | None = None)

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.

Parameters:

session – the client session to use, or None to use the default session.

Example:

with tmp_project() as proj:
    model = proj.create_model_obj()