Prefect Legacy API Documentation

# Client

# Client

class

prefect.client.client.Client

(api_server=None, api_token=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. The token will only be present in the current context.

Args:

  • api_server (str, optional): the URL to send all GraphQL requests to; if not provided, will be pulled from cloud.graphql config var
  • api_token (str, optional): a Prefect Cloud API token, taken from config.cloud.auth_token if not provided. If this token is USER-scoped, it may be used to log in to any tenant that the user is a member of. In that case, ephemeral JWTs will be loaded as necessary. Otherwise, the API token itself will be used as authorization.

methods:                                                                                                                                                       

prefect.client.client.Client.create_flow_run

(flow_id, context=None, parameters=None, scheduled_start_time=None, idempotency_key=None, run_name=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.

Args:

  • flow_id (str): 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
  • 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
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

Args:

  • project_name (str): the project that should contain this flow
  • project_description (str, optional): the project description
Returns:
  • str: the ID of the newly-created project
Raises:
  • ClientError: if the project creation failed

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.deploy

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

Push a new flow to Prefect Cloud

Args:

  • flow (Flow): a flow to deploy
  • project_name (str): the project that should contain this flow.
  • build (bool, optional): if True, the flow's environment 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
Returns:
  • str: the ID of the newly-deployed flow
Raises:
  • ClientError: if the deploy failed

prefect.client.client.Client.get

(path, server=None, headers=None, params=None, token=None)[source]

Convenience function for calling the Prefect API with token 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
  • token (str): an auth token. If not supplied, the client.access_token is used.
Returns:
  • dict: Dictionary representation of the request made

prefect.client.client.Client.get_auth_token

()[source]

Returns an auth token: - if no explicit access token is stored, returns the api token - if there is an access token: - if there's a refresh token and the access token expires in the next 30 seconds, then we refresh the access token and store the result - return the access token

Returns:

  • str: the access token

prefect.client.client.Client.get_available_tenants

()[source]

Returns a list of available tenants.

NOTE: this should only be called by users who have provided a USER-scoped API token.

Returns:

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

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_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_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, token=None)[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
  • token (str): an auth token. If not supplied, the client.access_token is used.
Returns:
  • dict: Data returned from the GraphQL query
Raises:
  • ClientError if there are errors raised by the GraphQL mutation

prefect.client.client.Client.login_to_tenant

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

Log in to a specific tenant

NOTE: this should only be called by users who have provided a USER-scoped API token.

Args:

  • tenant_slug (str): the tenant's slug
  • tenant_id (str): the tenant's id
Returns:
  • bool: True if the login was successful
Raises:
  • ValueError: if at least one of tenant_slug or tenant_id isn't provided
  • ValueError: if the tenant_id is not a valid UUID
  • ValueError: if no matching tenants are found

prefect.client.client.Client.logout_from_tenant

()[source]

prefect.client.client.Client.post

(path, server=None, headers=None, params=None, token=None)[source]

Convenience function for calling the Prefect API with token 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
  • token (str): an auth token. If not supplied, the client.access_token is used.
Returns:
  • dict: Dictionary representation of the request made

prefect.client.client.Client.save_api_token

()[source]

Saves the API token in local storage.

prefect.client.client.Client.set_flow_run_state

(flow_run_id, version, state)[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
  • version (int): the current version of the flow run state
  • state (State): the new state for this flow run
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_state

(task_run_id, version, state, 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
  • version (int): the current version of the task run state
  • state (State): the new state for this task run
  • 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.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_heartbeat

(task_run_id)[source]

Convenience method for heartbeating a task run.

Does NOT raise an error if the update fails.

Args:

  • task_run_id (str): the task run ID to heartbeat

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_log

(flow_run_id, task_run_id=None, timestamp=None, name=None, message=None, level=None, info=None)[source]

Uploads a log to Cloud.

Args:

  • flow_run_id (str): the flow run id
  • task_run_id (str, optional): the task run id
  • timestamp (datetime, optional): the timestamp; defaults to now
  • name (str, optional): the name of the logger
  • message (str, optional): the log message
  • level (str, optional): the log level as a string. Defaults to INFO, should be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL.
  • info (Any, optional): a JSON payload of additional information
Raises:
  • ValueError: if writing the log fails

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 n/a
on November 26, 2019 at 16:53 UTC

← Secrets →