Prefect Docs

# Client

# Client

class

prefect.client.client.Client

(api_server=None, api_key=None, tenant_id=None)[source]

Client for communication with Prefect Cloud

If the arguments aren't specified the client initialization first checks the prefect configuration and if the server is not set there it checks the current context.

Args:

  • api_server (str, optional): the URL to send all GraphQL requests to; if not provided, will be pulled from the current backend's api config variable
  • api_key (str, optional): a Prefect Cloud API key. If not provided, loaded from config.cloud.api_key or from the on disk cache from the prefect auth CLI
  • tenant_id (str, optional): the Prefect tenant to use. If not provided, loaded from config.cloud.tenant_id or the on disk cache from the prefect auth CLI

methods:                                                                                                                                                       

prefect.client.client.Client.attach_headers

(headers)[source]

Set headers to be attached to this Client

Args:

  • headers (dict): A dictionary of headers to attach to this client. These headers get added on to the existing dictionary of headers.

prefect.client.client.Client.cancel_flow_run

(flow_run_id)[source]

Cancel the flow run by id

Args:

  • flow_run_id (str): the id of the flow run
Returns:
  • bool: whether or not the flow run was canceled

prefect.client.client.Client.create_flow_run

(flow_id=None, context=None, parameters=None, run_config=None, labels=None, scheduled_start_time=None, idempotency_key=None, run_name=None, version_group_id=None)[source]

Create a new flow run for the given flow id. If start_time is not provided, the flow run will be scheduled to start immediately. If both flow_id and version_group_id are provided, only the flow_id will be used.

Args:

  • flow_id (str, optional): the id of the Flow you wish to schedule
  • context (dict, optional): the run context
  • parameters (dict, optional): a dictionary of parameter values to pass to the flow run
  • run_config (RunConfig, optional): a run-config to use for this flow run, overriding any existing flow settings.
  • labels (List[str], optional): a list of labels to apply to the flow run
  • scheduled_start_time (datetime, optional): the time to schedule the execution for; if not provided, defaults to now
  • idempotency_key (str, optional): an idempotency key; if provided, this run will be cached for 24 hours. Any subsequent attempts to create a run with the same idempotency key will return the ID of the originally created run (no new run will be created after the first). An error will be raised if parameters or context are provided and don't match the original. Each subsequent request will reset the TTL for 24 hours.
  • run_name (str, optional): The name assigned to this flow run
  • version_group_id (str, optional): if provided, the unique unarchived flow within this version group will be scheduled to run. This input can be used as a stable API for running flows which are regularly updated.
Returns:
  • str: the ID of the newly-created flow run
Raises:
  • ClientError: if the GraphQL query is bad for any reason

prefect.client.client.Client.create_project

(project_name, project_description=None)[source]

Create a new project if a project with the name provided does not already exist

Args:

  • project_name (str): the project that should be created
  • project_description (str, optional): the project description
Returns:
  • str: the ID of the newly-created or pre-existing project
Raises:
  • ClientError: if the project creation failed

prefect.client.client.Client.create_task_run_artifact

(task_run_id, kind, data, tenant_id=None)[source]

Create an artifact that corresponds to a specific task run

Args:

  • task_run_id (str): the task run id
  • kind (str): the artifact kind
  • data (dict): the artifact data
  • tenant_id (str, optional): the tenant id that this artifact belongs to. Defaults to the tenant ID linked to the task run
Returns:
  • str: the task run artifact ID

prefect.client.client.Client.create_tenant

(name, slug=None)[source]

Creates a new tenant.

Note this route only works when run against Prefect Server.

Args:

  • name (str): the name of the tenant to create
  • slug (str, optional): the slug of the tenant to create; defaults to name
Returns:
  • str: the ID of the newly created tenant, or the ID of the currently active tenant
Raises:
  • ValueError: if run against Prefect Cloud

prefect.client.client.Client.delete_project

(project_name)[source]

Delete a project

Args:

  • project_name (str): the project that should be created
Returns:
  • bool: True if project is deleted else False Raises:
  • ValueError: if the project is None or doesn't exist

prefect.client.client.Client.delete_task_run_artifact

(task_run_artifact_id)[source]

Delete an artifact that corresponds to a specific task run

Args:

  • task_run_artifact_id (str): the task run artifact id

prefect.client.client.Client.delete_task_tag_limit

(limit_id)[source]

Deletes a given task tag concurrency limit; requires tenant admin permissions.

Args:

  • limit_id (str): the ID of the tag to delete
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason
  • ValueError: if the tag deletion was unsuccessful, or if a bad tag ID was provided

prefect.client.client.Client.get

(path, server=None, headers=None, params=None, api_key=None, retry_on_api_error=True)[source]

Convenience function for calling the Prefect API with auth and GET request

Args:

  • path (str): the path of the API url. For example, to GET http://prefect-server/v1/auth/login, path would be 'auth/login'.
  • server (str, optional): the server to send the GET request to; defaults to self.api_server
  • headers (dict, optional): Headers to pass with the request
  • params (dict): GET parameters
  • api_key (str): An api key for auth. Defaults to client.api_key.
  • retry_on_api_error (bool): whether the operation should be retried if the API returns an API_ERROR code
Returns:
  • dict: Dictionary representation of the request made

prefect.client.client.Client.get_agent_config

(agent_config_id)[source]

Get agent config settings

Args:

  • agent_config_id (str): The ID of an agent configuration to retrieve
Returns:
  • dict: the agent configuration's settings

prefect.client.client.Client.get_available_tenants

()[source]

Returns a list of available tenants.

Returns:

  • List[Dict]: a list of dictionaries containing the id, slug, and name of available tenants

prefect.client.client.Client.get_cloud_url

(subdirectory, id)[source]

Convenience method for creating Prefect Cloud URLs for a given subdirectory.

Args:

  • subdirectory (str): the subdirectory to use (e.g., "flow-run")
  • id (str): the ID of the page
Returns:
  • str: the URL corresponding to the appropriate base URL, tenant slug, subdirectory and ID
Example:


from prefect import Client

client = Client()
client.get_cloud_url("flow-run", "424242-ca-94611-111-55")
# returns "https://cloud.prefect.io/my-tenant-slug/flow-run/424242-ca-94611-111-55"

prefect.client.client.Client.get_default_tenant_slug

()[source]

Get the default tenant slug for the currently authenticated user

Returns:

  • str: the slug of the current default tenant for this user

prefect.client.client.Client.get_flow_run_info

(flow_run_id)[source]

Retrieves version and current state information for the given flow run.

Args:

  • flow_run_id (str): the id of the flow run to get information for
Returns:
  • GraphQLResult: an object representing information about the flow run
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason

prefect.client.client.Client.get_flow_run_state

(flow_run_id)[source]

Retrieves the current state for a flow run.

Args:

  • flow_run_id (str): the id for this flow run
Returns:
  • State: a Prefect State object

prefect.client.client.Client.get_latest_cached_states

(task_id, cache_key, created_after)[source]

Pulls all Cached states for the given task that were created after the provided date.

Args:

  • task_id (str): the task id for this task run
  • cache_key (Optional[str]): the cache key for this Task's cache; if None, the task id alone will be used
  • created_after (datetime.datetime): the earliest date the state should have been created at
Returns:
  • List[State]: a list of Cached states created after the given date

prefect.client.client.Client.get_task_run_info

(flow_run_id, task_id, map_index=None)[source]

Retrieves version and current state information for the given task run.

Args:

  • flow_run_id (str): the id of the flow run that this task run lives in
  • task_id (str): the task id for this task run
  • map_index (int, optional): the mapping index for this task run; if None, it is assumed this task is not mapped
Returns:
  • NamedTuple: a tuple containing id, task_id, version, state
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason

prefect.client.client.Client.get_task_run_state

(task_run_id)[source]

Retrieves the current state for a task run.

Args:

  • task_run_id (str): the id for this task run
Returns:
  • State: a Prefect State object

prefect.client.client.Client.get_task_tag_limit

(tag)[source]

Retrieve the current task tag concurrency limit for a given tag.

Args:

  • tag (str): the tag to update
Raises:
  • ClientError: if the GraphQL query fails

prefect.client.client.Client.graphql

(query, raise_on_error=True, headers=None, variables=None, api_key=None, retry_on_api_error=True)[source]

Convenience function for running queries against the Prefect GraphQL API

Args:

  • query (Any): A representation of a graphql query to be executed. It will be parsed by prefect.utilities.graphql.parse_graphql().
  • raise_on_error (bool): if True, a ClientError will be raised if the GraphQL returns any errors.
  • headers (dict): any additional headers that should be passed as part of the request
  • variables (dict): Variables to be filled into a query with the key being equivalent to the variables that are accepted by the query
  • api_key (str): An api key for auth. Defaults to client.api_key.
  • retry_on_api_error (bool): whether the operation should be retried if the API returns an API_ERROR code
Returns:
  • dict: Data returned from the GraphQL query
Raises:
  • ClientError if there are errors raised by the GraphQL mutation

prefect.client.client.Client.load_auth_from_disk

()[source]

Get the stashed api_key and tenant_id for the current api_server from the disk cache if it exists. If it does not, an empty dict is returned.

WARNING: This will not mutate the Client, you must use the returned dict to set api_key and tenant_id. This is

prefect.client.client.Client.post

(path, server=None, headers=None, params=None, api_key=None, retry_on_api_error=True)[source]

Convenience function for calling the Prefect API with auth and POST request

Args:

  • path (str): the path of the API url. For example, to POST http://prefect-server/v1/auth/login, path would be 'auth/login'.
  • server (str, optional): the server to send the POST request to; defaults to self.api_server
  • headers(dict): headers to pass with the request
  • params (dict): POST parameters
  • api_key (str): An api key for auth. Defaults to client.api_key.
  • retry_on_api_error (bool): whether the operation should be retried if the API returns an API_ERROR code
Returns:
  • dict: Dictionary representation of the request made

prefect.client.client.Client.register

(flow, project_name=None, build=True, set_schedule_active=True, version_group_id=None, compressed=True, no_url=False, idempotency_key=None)[source]

Register a new flow with Prefect Cloud.

Args:

  • flow (Flow): a flow to register
  • project_name (str, optional): the project that should contain this flow.
  • build (bool, optional): if True, the flow's storage is built prior to serialization; defaults to True
  • set_schedule_active (bool, optional): if False, will set the schedule to inactive in the database to prevent auto-scheduling runs (if the Flow has a schedule). Defaults to True. This can be changed later.
  • version_group_id (str, optional): the UUID version group ID to use for versioning this Flow in Cloud; if not provided, the version group ID associated with this Flow's project and name will be used.
  • compressed (bool, optional): if True, the serialized flow will be; defaults to True compressed
  • no_url (bool, optional): if True, the stdout from this function will not contain the URL link to the newly-registered flow in the Cloud UI
  • idempotency_key (optional, str): a key that, if matching the most recent registration call for this flow group, will prevent the creation of another flow version and return the existing flow id instead.
Returns:
  • str: the ID of the newly-registered flow
Raises:
  • ClientError: if the registration failed

prefect.client.client.Client.register_agent

(agent_type, name=None, labels=None, agent_config_id=None)[source]

Register an agent with a backend API

Args:

  • agent_type (str): The type of agent being registered
  • name: (str, optional): The name of the agent being registered
  • labels (List[str], optional): A list of any present labels on the agent being registered
  • agent_config_id (str, optional): The ID of an agent configuration to register with
Returns:
  • The agent ID as a string

prefect.client.client.Client.save_auth_to_disk

()[source]

Write the current auth information to the disk cache under a header for the current api_server

prefect.client.client.Client.set_flow_run_name

(flow_run_id, name)[source]

Set the name of a flow run.

Args:

  • flow_run_id (str): the id of a flow run
  • name (str): a name for this flow run
Returns:
  • bool: whether or not the flow run name was updated

prefect.client.client.Client.set_flow_run_state

(flow_run_id, state, version=None)[source]

Sets new state for a flow run in the database.

Args:

  • flow_run_id (str): the id of the flow run to set state for
  • state (State): the new state for this flow run
  • version (int, optional): the current version of the flow run state. This is optional but it can be supplied to enforce version-locking.
Returns:
  • State: the state the current flow run should be considered in
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason

prefect.client.client.Client.set_secret

(name, value)[source]

Set a secret with the given name and value.

Args:

  • name (str): the name of the secret; used for retrieving the secret during task runs
  • value (Any): the value of the secret
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason
  • ValueError: if the secret-setting was unsuccessful

prefect.client.client.Client.set_task_run_name

(task_run_id, name)[source]

Set the name of a task run

Args:

  • task_run_id (str): the id of a task run
  • name (str): a name for this task run
Returns:
  • bool: whether or not the task run name was updated

prefect.client.client.Client.set_task_run_state

(task_run_id, state, version=None, cache_for=None)[source]

Sets new state for a task run.

Args:

  • task_run_id (str): the id of the task run to set state for
  • state (State): the new state for this task run
  • version (int, optional): the current version of the task run state. This is optional but it can be supplied to enforce version-locking.
  • cache_for (timedelta, optional): how long to store the result of this task for, using the serializer set in config; if not provided, no caching occurs
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason
Returns:
  • State: the state the current task run should be considered in

prefect.client.client.Client.switch_tenant

(tenant_slug=None, tenant_id=None)[source]

Switch this client to the given tenant by slug or tenant id.

The client tenant will be updated but will not be saved to disk without an explicit call.

Args:

  • tenant_slug (str): the tenant's slug
  • tenant_id (str): the tenant's id
Returns:
  • str: The id of the tenant
Raises:
  • ValueError: if no matching tenants are found
  • ValueError: both slug and id are provided
  • AuthenticationError: if the key is not valid for the given tenant

prefect.client.client.Client.update_flow_run_heartbeat

(flow_run_id)[source]

Convenience method for heartbeating a flow run.

Does NOT raise an error if the update fails.

Args:

  • flow_run_id (str): the flow run ID to heartbeat

prefect.client.client.Client.update_task_run_artifact

(task_run_artifact_id, data)[source]

Update an artifact that corresponds to a specific task run

Args:

  • task_run_artifact_id (str): the task run artifact id
  • data (dict): the artifact data

prefect.client.client.Client.update_task_tag_limit

(tag, limit)[source]

Update the task tag concurrency limit for a given tag; requires tenant admin permissions.

Args:

  • tag (str): the tag to update
  • limit (int): the concurrency limit to enforce on the tag; should be a value >= 0
Raises:
  • ClientError: if the GraphQL mutation is bad for any reason
  • ValueError: if the tag limit-setting was unsuccessful, or if a bad limit was provided

prefect.client.client.Client.write_run_logs

(logs)[source]

Uploads a collection of logs to Cloud.

Args:

  • logs (List[Dict]): a list of log entries to add
Raises:
  • ValueError: if uploading the logs fail


This documentation was auto-generated from commit ffa9a6c
on February 1, 2023 at 18:44 UTC

← Secrets →